[all][PTL][tc] U Community Goal: Project PTL & Contrib Docs Update #3

Kendall Nelson kennelson11 at gmail.com
Thu Feb 27 19:15:04 UTC 2020

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 at gmail.com>

> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20200227/cf9f1aa2/attachment-0001.html>

More information about the openstack-discuss mailing list