Open Stack

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 at 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:
>
>    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.html
> [5] Update #2: http://lists.openstack.org/pipermail/openstack-discuss/2020-February/012570.html