[all][PTL][tc] U Community Goal: Project PTL & Contrib Docs Update #3
Hello!
There is some debate about where the content of the actual docs should live. This grew out of the discussion about how to setup the includes so that the correct info shows up where we want it. 'Correct' in that last sentence being where the debate is. There are two main schools of thought:
1. All the content of the docs should live in the top level CONTRIBUTING.rst and the sphinx glue should live in doc/source/contributor/contributing.rst. A patch has already been merged for this approach[1]. There is also a patch to update the goal to match[2]. This approach keeps all the info in one place so that if things change in the future, its easier to keep things straight. All the content is also more easily discoverable when looking at a repo in GitHub (or similar) or checking out the code because it is at the top most level of the repo and not hidden in the docs sub directory.
2. The new patch[3] says that the content should live in /doc/source/contributor/contributing.rst and a skeleton with only the most important version should live in the top level CONTRIBUTING.rst. This approach argues that people don't want to read a wall of text when viewing the code on GitHub (or similar) or checking it out and looking at the top level CONTRIBUTING.rst and as such only the important details should be kept in that file. These important details being that we don't accept patches in github and where to report bugs (both of which are included in the larger format of the content).
So what do people think? Which approach do they prefer?
I am anxious to get this settled ASAP so that projects have time to complete the goal in time.
Previous updates if you missed them[4][5].
Please feel free to add other ideas or make corrections to my summaries of the approaches if I missed things :)
-Kendall (diablo_rojo)
[1] Merged Template Patch (school of thought 1): https://review.opendev.org/#/c/708511/ [2] Goal Update Patch: https://review.opendev.org/#/c/707736/ [3] Current Template Patch (school of thought 2): https://review.opendev.org/#/c/708672/ [4] Update #1: http://lists.openstack.org/pipermail/openstack-discuss/2020-February/012364.... [5] Update #2: http://lists.openstack.org/pipermail/openstack-discuss/2020-February/012570....
Hi Kendall,
Personally I lean towards option #2, simply because I like the idea of potentially splitting out the contributing content into multiple files. This aligns to our current contributor guide which has pages for various ways you can contribute to OpenStack [1].
For example, I could envision a page in the Octavia documentation for new code contributors, a page for the PTL role (this goal), a page for provider driver contributors [2], etc.
Really this content seems like more information than should be on a single page (coming from someone that has authored some long pages already, see above provider driver guide[2]).
My $0.02. Thanks again for leading this effort.
Michael
[1] https://docs.openstack.org/contributors [2] https://docs.openstack.org/octavia/latest/contributor/guides/providers.html
On Mon, Feb 24, 2020 at 11:47 AM Kendall Nelson kennelson11@gmail.com wrote:
Hello!
There is some debate about where the content of the actual docs should live. This grew out of the discussion about how to setup the includes so that the correct info shows up where we want it. 'Correct' in that last sentence being where the debate is. There are two main schools of thought:
All the content of the docs should live in the top level CONTRIBUTING.rst and the sphinx glue should live in doc/source/contributor/contributing.rst. A patch has already been merged for this approach[1]. There is also a patch to update the goal to match[2]. This approach keeps all the info in one place so that if things change in the future, its easier to keep things straight. All the content is also more easily discoverable when looking at a repo in GitHub (or similar) or checking out the code because it is at the top most level of the repo and not hidden in the docs sub directory.
The new patch[3] says that the content should live in /doc/source/contributor/contributing.rst and a skeleton with only the most important version should live in the top level CONTRIBUTING.rst. This approach argues that people don't want to read a wall of text when viewing the code on GitHub (or similar) or checking it out and looking at the top level CONTRIBUTING.rst and as such only the important details should be kept in that file. These important details being that we don't accept patches in github and where to report bugs (both of which are included in the larger format of the content).
So what do people think? Which approach do they prefer?
I am anxious to get this settled ASAP so that projects have time to complete the goal in time.
Previous updates if you missed them[4][5].
Please feel free to add other ideas or make corrections to my summaries of the approaches if I missed things :)
-Kendall (diablo_rojo)
[1] Merged Template Patch (school of thought 1): https://review.opendev.org/#/c/708511/ [2] Goal Update Patch: https://review.opendev.org/#/c/707736/ [3] Current Template Patch (school of thought 2): https://review.opendev.org/#/c/708672/ [4] Update #1:http://lists.openstack.org/pipermail/openstack-discuss/2020-February/012364.... [5] Update #2: http://lists.openstack.org/pipermail/openstack-discuss/2020-February/012570....
On Mon, 2020-02-24 at 14:25 -0800, Michael Johnson wrote:
For example, I could envision a page in the Octavia documentation for new code contributors, a page for the PTL role (this goal), a page for provider driver contributors [2], etc.
I think one of the ideas was to standardize, so maybe we shouldn't eventually diverge too much? (Which will happen anyway, but maybe we should keep a mental note to try to remain standard, and behave all the same way...)
Really this content seems like more information than should be on a single page (coming from someone that has authored some long pages already, see above provider driver guide[2]).
Agreed.
My $0.02. Thanks again for leading this effort.
Hey, a cent is worth a lot apparently, thanks for giving two of those! ;) Thanks indeed for the work Kendall and crew.
On Mon, Feb 24, 2020 at 11:47 AM Kendall Nelson < kennelson11@gmail.com> wrote:
So what do people think? Which approach do they prefer?
I prefer option 2, but I would say that I also trust you to come with the best solution with your experience. Waiting for review on the alternative patch chain.
Regards, JP
Kendall Nelson wrote:
There is some debate about where the content of the actual docs should live. This grew out of the discussion about how to setup the includes so that the correct info shows up where we want it. 'Correct' in that last sentence being where the debate is. There are two main schools of thought:
1. All the content of the docs should live in the top level CONTRIBUTING.rst and the sphinx glue should live in doc/source/contributor/contributing.rst. A patch has already been merged for this approach[1]. There is also a patch to update the goal to match[2]. This approach keeps all the info in one place so that if things change in the future, its easier to keep things straight. All the content is also more easily discoverable when looking at a repo in GitHub (or similar) or checking out the code because it is at the top most level of the repo and not hidden in the docs sub directory.
2. The new patch[3] says that the content should live in /doc/source/contributor/contributing.rst and a skeleton with only the most important version should live in the top level CONTRIBUTING.rst. This approach argues that people don't want to read a wall of text when viewing the code on GitHub (or similar) or checking it out and looking at the top level CONTRIBUTING.rst and as such only the important details should be kept in that file. These important details being that we don't accept patches in github and where to report bugs (both of which are included in the larger format of the content).
So what do people think? Which approach do they prefer?
I personally prefer a single page approach (school 1). That said, I think we need to be very careful to keep this page to a minimum, to avoid the "wall of text" effect.
In particular, I think:
- "Communication" / "Contacting the Core team" could be collapsed into a single section
- "Task tracking" / "Reporting a bug" could be collapsed into a single section
- "Project team lead duties" sounds a bit overkill for a first-contact doc, can probably be documented elsewhere.
- Sections could be reordered in order of likely involvement: How to talk with the team, So you want to report a bug, So you want to propose a change, So you want to propose a new feature.
I am anxious to get this settled ASAP so that projects have time to complete the goal in time.
Agree it would be good to come up with a consensus on this ASAP. Maybe the TC can settle it at next week meeting.
So, maybe a hybrid.
For example, have a standard "Contributing.rst", with fixed template/content, that can link off to these other guides? (I feel like this might be the original idea and I just missed the concept, lol)
Maybe we need two templates. one for "contributing.rst" in the root (boilerplate-ish) and one template for inside the documentation tree ("how-to-contribute.rst ???). This seems similar to what we have today, but with a more formal template for the "how-to-contribute" landing page.
To some degree there is a strange overlap here with the existing "contributor" section of the documentation that has the gory coding details, etc.
I still lean towards having the "slightly more verbose" version in the documentation tree as then we can use the sphinx magic for glossary linking, internal links, etc.
Michael
On Tue, Feb 25, 2020 at 2:56 AM Thierry Carrez thierry@openstack.org wrote:
Kendall Nelson wrote:
There is some debate about where the content of the actual docs should live. This grew out of the discussion about how to setup the includes so that the correct info shows up where we want it. 'Correct' in that last sentence being where the debate is. There are two main schools of thought:
1. All the content of the docs should live in the top levelCONTRIBUTING.rst and the sphinx glue should live in doc/source/contributor/contributing.rst. A patch has already been merged for this approach[1]. There is also a patch to update the goal to match[2]. This approach keeps all the info in one place so that if things change in the future, its easier to keep things straight. All the content is also more easily discoverable when looking at a repo in GitHub (or similar) or checking out the code because it is at the top most level of the repo and not hidden in the docs sub directory.
2. The new patch[3] says that the content should live in/doc/source/contributor/contributing.rst and a skeleton with only the most important version should live in the top level CONTRIBUTING.rst. This approach argues that people don't want to read a wall of text when viewing the code on GitHub (or similar) or checking it out and looking at the top level CONTRIBUTING.rst and as such only the important details should be kept in that file. These important details being that we don't accept patches in github and where to report bugs (both of which are included in the larger format of the content).
So what do people think? Which approach do they prefer?
I personally prefer a single page approach (school 1). That said, I think we need to be very careful to keep this page to a minimum, to avoid the "wall of text" effect.
In particular, I think:
- "Communication" / "Contacting the Core team" could be collapsed into a
single section
- "Task tracking" / "Reporting a bug" could be collapsed into a single
section
- "Project team lead duties" sounds a bit overkill for a first-contact
doc, can probably be documented elsewhere.
- Sections could be reordered in order of likely involvement: How to
talk with the team, So you want to report a bug, So you want to propose a change, So you want to propose a new feature.
I am anxious to get this settled ASAP so that projects have time to complete the goal in time.
Agree it would be good to come up with a consensus on this ASAP. Maybe the TC can settle it at next week meeting.
-- Thierry Carrez (ttx)
On 25/02/20 12:33 pm, Michael Johnson wrote:
So, maybe a hybrid.
For example, have a standard "Contributing.rst", with fixed template/content, that can link off to these other guides? (I feel like this might be the original idea and I just missed the concept, lol)
Maybe we need two templates. one for "contributing.rst" in the root (boilerplate-ish) and one template for inside the documentation tree ("how-to-contribute.rst ???). This seems similar to what we have today, but with a more formal template for the "how-to-contribute" landing page.
That sounds very similar to what's actually proposed for option 2: https://review.opendev.org/708672
To some degree there is a strange overlap here with the existing "contributor" section of the documentation that has the gory coding details, etc.
I still lean towards having the "slightly more verbose" version in the documentation tree as then we can use the sphinx magic for glossary linking, internal links, etc.
Agreed. It should also be noted that some of the people reading CONTRIBUTING.rst will just be doing so in their local checkout/tarball using cat/less. Making them read full on rst formatting, complete with comments and stuff is probably not the best experience. The current document (e.g. https://opendev.org/openstack/nova/raw/branch/master/CONTRIBUTING.rst) is actually very good at that and AFAIK is actually pretty consistent across all of our repos.
I also just don't think that the full on contribution template is the right information for the audience that will read CONTRIBUTING.rst. If someone is looking at that file, it's because they either have a local checkout or a tarball from somewhere and they want to know how to make their first contribution, or because they're already trying to open a PR on GitHub for their first contribution. They need to know where the canonical repo and the bug tracker is and how to submit a bug or patch; they don't need to know what the PTL's duties are at that moment.
cheers, Zane.
Michael
On Tue, Feb 25, 2020 at 2:56 AM Thierry Carrez thierry@openstack.org wrote:
Kendall Nelson wrote:
There is some debate about where the content of the actual docs should live. This grew out of the discussion about how to setup the includes so that the correct info shows up where we want it. 'Correct' in that last sentence being where the debate is. There are two main schools of thought:
1. All the content of the docs should live in the top levelCONTRIBUTING.rst and the sphinx glue should live in doc/source/contributor/contributing.rst. A patch has already been merged for this approach[1]. There is also a patch to update the goal to match[2]. This approach keeps all the info in one place so that if things change in the future, its easier to keep things straight. All the content is also more easily discoverable when looking at a repo in GitHub (or similar) or checking out the code because it is at the top most level of the repo and not hidden in the docs sub directory.
2. The new patch[3] says that the content should live in/doc/source/contributor/contributing.rst and a skeleton with only the most important version should live in the top level CONTRIBUTING.rst. This approach argues that people don't want to read a wall of text when viewing the code on GitHub (or similar) or checking it out and looking at the top level CONTRIBUTING.rst and as such only the important details should be kept in that file. These important details being that we don't accept patches in github and where to report bugs (both of which are included in the larger format of the content).
So what do people think? Which approach do they prefer?
I personally prefer a single page approach (school 1). That said, I think we need to be very careful to keep this page to a minimum, to avoid the "wall of text" effect.
In particular, I think:
- "Communication" / "Contacting the Core team" could be collapsed into a
single section
- "Task tracking" / "Reporting a bug" could be collapsed into a single
section
- "Project team lead duties" sounds a bit overkill for a first-contact
doc, can probably be documented elsewhere.
- Sections could be reordered in order of likely involvement: How to
talk with the team, So you want to report a bug, So you want to propose a change, So you want to propose a new feature.
I am anxious to get this settled ASAP so that projects have time to complete the goal in time.
Agree it would be good to come up with a consensus on this ASAP. Maybe the TC can settle it at next week meeting.
-- Thierry Carrez (ttx)
Hi,
On 26 Feb 2020, at 02:56, Zane Bitter zbitter@redhat.com wrote:
On 25/02/20 12:33 pm, Michael Johnson wrote:
So, maybe a hybrid. For example, have a standard "Contributing.rst", with fixed template/content, that can link off to these other guides? (I feel like this might be the original idea and I just missed the concept, lol) Maybe we need two templates. one for "contributing.rst" in the root (boilerplate-ish) and one template for inside the documentation tree ("how-to-contribute.rst ???). This seems similar to what we have today, but with a more formal template for the "how-to-contribute" landing page.
That sounds very similar to what's actually proposed for option 2: https://review.opendev.org/708672
To some degree there is a strange overlap here with the existing "contributor" section of the documentation that has the gory coding details, etc. I still lean towards having the "slightly more verbose" version in the documentation tree as then we can use the sphinx magic for glossary linking, internal links, etc.
Agreed. It should also be noted that some of the people reading CONTRIBUTING.rst will just be doing so in their local checkout/tarball using cat/less. Making them read full on rst formatting, complete with comments and stuff is probably not the best experience. The current document (e.g. https://opendev.org/openstack/nova/raw/branch/master/CONTRIBUTING.rst) is actually very good at that and AFAIK is actually pretty consistent across all of our repos.
I also just don't think that the full on contribution template is the right information for the audience that will read CONTRIBUTING.rst. If someone is looking at that file, it's because they either have a local checkout or a tarball from somewhere and they want to know how to make their first contribution, or because they're already trying to open a PR on GitHub for their first contribution. They need to know where the canonical repo and the bug tracker is and how to submit a bug or patch; they don't need to know what the PTL's duties are at that moment.
I totally agree with that. IMHO we should keep top-level CONTRIBUTING.rst file short and link to more detailed guide which will be in contributor/contributing.rst.
cheers, Zane.
Michael On Tue, Feb 25, 2020 at 2:56 AM Thierry Carrez thierry@openstack.org wrote:
Kendall Nelson wrote:
There is some debate about where the content of the actual docs should live. This grew out of the discussion about how to setup the includes so that the correct info shows up where we want it. 'Correct' in that last sentence being where the debate is. There are two main schools of thought:
1. All the content of the docs should live in the top levelCONTRIBUTING.rst and the sphinx glue should live in doc/source/contributor/contributing.rst. A patch has already been merged for this approach[1]. There is also a patch to update the goal to match[2]. This approach keeps all the info in one place so that if things change in the future, its easier to keep things straight. All the content is also more easily discoverable when looking at a repo in GitHub (or similar) or checking out the code because it is at the top most level of the repo and not hidden in the docs sub directory.
2. The new patch[3] says that the content should live in/doc/source/contributor/contributing.rst and a skeleton with only the most important version should live in the top level CONTRIBUTING.rst. This approach argues that people don't want to read a wall of text when viewing the code on GitHub (or similar) or checking it out and looking at the top level CONTRIBUTING.rst and as such only the important details should be kept in that file. These important details being that we don't accept patches in github and where to report bugs (both of which are included in the larger format of the content).
So what do people think? Which approach do they prefer?
I personally prefer a single page approach (school 1). That said, I think we need to be very careful to keep this page to a minimum, to avoid the "wall of text" effect.
In particular, I think:
- "Communication" / "Contacting the Core team" could be collapsed into a
single section
- "Task tracking" / "Reporting a bug" could be collapsed into a single
section
- "Project team lead duties" sounds a bit overkill for a first-contact
doc, can probably be documented elsewhere.
- Sections could be reordered in order of likely involvement: How to
talk with the team, So you want to report a bug, So you want to propose a change, So you want to propose a new feature.
I am anxious to get this settled ASAP so that projects have time to complete the goal in time.
Agree it would be good to come up with a consensus on this ASAP. Maybe the TC can settle it at next week meeting.
-- Thierry Carrez (ttx)
— Slawek Kaplonski Senior software engineer Red Hat
It seems like most people being vocal (thank you for your opinions btw :) ) are leaning towards approach number 2 so I guess if no one has any real objections we should get these patches merged[1][2][3] so that projects can make progress on the goal.
I think we can still complete it in this cycle and am willing to help projects that are concerned about the deadline.
-Kendall (diablo_rojo)
[1] Cookie Cutter Change https://review.opendev.org/#/c/708672/ [2] Governance Goal Change https://review.opendev.org/#/c/709617/ [3] Governance Goal Change Typo Fix https://review.opendev.org/#/c/710332/1
On Mon, Feb 24, 2020 at 11:44 AM Kendall Nelson kennelson11@gmail.com wrote:
Hello!
There is some debate about where the content of the actual docs should live. This grew out of the discussion about how to setup the includes so that the correct info shows up where we want it. 'Correct' in that last sentence being where the debate is. There are two main schools of thought:
- All the content of the docs should live in the top level
CONTRIBUTING.rst and the sphinx glue should live in doc/source/contributor/contributing.rst. A patch has already been merged for this approach[1]. There is also a patch to update the goal to match[2]. This approach keeps all the info in one place so that if things change in the future, its easier to keep things straight. All the content is also more easily discoverable when looking at a repo in GitHub (or similar) or checking out the code because it is at the top most level of the repo and not hidden in the docs sub directory.
2. The new patch[3] says that the content should live in/doc/source/contributor/contributing.rst and a skeleton with only the most important version should live in the top level CONTRIBUTING.rst. This approach argues that people don't want to read a wall of text when viewing the code on GitHub (or similar) or checking it out and looking at the top level CONTRIBUTING.rst and as such only the important details should be kept in that file. These important details being that we don't accept patches in github and where to report bugs (both of which are included in the larger format of the content).
So what do people think? Which approach do they prefer?
I am anxious to get this settled ASAP so that projects have time to complete the goal in time.
Previous updates if you missed them[4][5].
Please feel free to add other ideas or make corrections to my summaries of the approaches if I missed things :)
-Kendall (diablo_rojo)
[1] Merged Template Patch (school of thought 1): https://review.opendev.org/#/c/708511/ [2] Goal Update Patch: https://review.opendev.org/#/c/707736/ [3] Current Template Patch (school of thought 2): https://review.opendev.org/#/c/708672/ [4] Update #1: http://lists.openstack.org/pipermail/openstack-discuss/2020-February/012364.... [5] Update #2: http://lists.openstack.org/pipermail/openstack-discuss/2020-February/012570....
participants (6)
-
Jean-Philippe Evrard
-
Kendall Nelson
-
Michael Johnson
-
Slawek Kaplonski
-
Thierry Carrez
-
Zane Bitter