From a5acc83c21030dfe484e188ea5881b92ffda78f4 Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Thu, 3 Aug 2017 16:36:10 -0400 Subject: [PATCH] Add Contributor Guide section page In order to wrangle together a top level TOC that makes sense, stop including everything in the TOC (ideally we could convince sphinx to not warn on that). This creates a Contributor Documentation landing page with deep links to all the relevant documents. It removes all those links from the front page, and the TOC. They can be found by deep links or search, and it is a less confusing initial experience for folks. Part of bp: doc-migration Change-Id: If5e7940ddd0ae3316f7475742c02abfe3df28ac4 --- doc/source/contributor/index.rst | 88 ++++++++++++++++++++++++++++++++ doc/source/index.rst | 67 ++++++++---------------- 2 files changed, 108 insertions(+), 47 deletions(-) create mode 100644 doc/source/contributor/index.rst diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000000..cfb399e08d --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,88 @@ +=========================== + Contributor Documentation +=========================== + +Contributing to nova gives you the power to help add features, fix bugs, +enhance documentation, and increase testing. Contributions of any type are +valuable, and part of what keeps the project going. Here are a list of +resources to get your started. + +Getting Started +=============== + +* :doc:`/contributor/how-to-get-involved`: Overview of engaging in the project +* :doc:`/contributor/development-environment`: Get your computer setup to + contribute + +Nova Process +============ + +The nova community is a large community. We have lots of users, and they all +have a lot of expectations around upgrade and backwards compatibility. For +example, having a good stable API, with discoverable versions and capabilities +is important for maintaining the strong ecosystem around Nova. + +Our process is always evolving, just as nova and the community around Nova +evolves over time. If there are things that seem strange, or you have ideas on +how to improve things, please bring them forward on IRC or the openstack-dev +mailing list, so we continue to improve how the nova community operates. + +This section looks at the processes and why. The main aim behind all the +process is to aid communication between all members of the nova community, +while keeping users happy and keeping developers productive. + +* :doc:`/contributor/project-scope`: The focus is on features and bug fixes + that make nova work better within this scope +* :doc:`/contributor/policies`: General guidelines about what's supported +* :doc:`/contributor/process`: The processes we follow around feature and bug + submission, including how the release calendar works, and the freezes we go + under +* :doc:`/contributor/blueprints`: An overview of our tracking artifacts. + +For Reviewers +============= + +* :doc:`/contributor/releasenotes`: When we need a release note for a + contribution. +* :doc:`/contributor/code-review`: important cheat sheet for what's important + when doing code review in Nova, especially some things that are hard to test + for, but need human eyes. + +Testing +======= + +Because Python is a dynamic language, code that is not testing might not even +be python code. All new code needs to be validated somehow. + +* :doc:`/contributor/testing`: An overview of our test taxonomy, and the kinds + of testing we do and expect. + +* **Testing Guides**: There are also specific testing guides for features that are + hard to test in our gate. + + * :doc:`/contributor/testing/libvirt-numa` + + * :doc:`/contributor/testing/serial-console` + + * :doc:`/contributor/testing/zero-downtime-upgrade` + +The Nova API +============ + +Because we have many consumers of our API, we're extremely careful about +changes done to the API, as the impact can be very wide. + +* :doc:`/contributor/api`: How the code is structured inside the API layer +* :doc:`/contributor/api-2`: (needs update) +* :doc:`/contributor/microversions`: we use microversions to version our API, + this walks you through what you need to do when adding an API exposed feature + that needs one. + +Nova Major Subsystems +===================== + +Major subsystems in Nova have different needs, some of those are documented +here. If you are contributing to one of these please read the subsystem guide +before diving in. + +* :doc:`/contributor/placement` diff --git a/doc/source/index.rst b/doc/source/index.rst index fb55385ad1..3288adc142 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -85,7 +85,6 @@ integration testing efforts. .. toctree:: :maxdepth: 1 - contributor/testing user/feature-classification user/support-matrix @@ -98,37 +97,7 @@ actually does, and why. .. toctree:: :maxdepth: 1 - contributor/how-to-get-involved - contributor/process - user/architecture - contributor/project-scope - contributor/development-environment - -Development Policies --------------------- - -The Nova community is a large community. We have lots of users, and they all -have a lot of expectations around upgrade and backwards compatibility. -For example, having a good stable API, with discoverable versions and -capabilities is important for maintaining the strong ecosystem around Nova. - -Our process is always evolving, just as Nova and the community around Nova -evolves over time. If there are things that seem strange, or you have -ideas on how to improve things, please engage in that debate, so we -continue to improve how the Nova community operates. - -This section looks at the processes and why. The main aim behind all the -process is to aid good communication between all members of the Nova -community, while keeping users happy and keeping developers productive. - -.. toctree:: - :maxdepth: 1 - - contributor/process - contributor/blueprints - contributor/policies - contributor/code-review - contributor/releasenotes + contributor/index Architecture Concepts ---------------------- @@ -146,8 +115,8 @@ Open Development. .. toctree:: :maxdepth: 1 - contributor/api-2 reference/rpc + user/architecture user/block-device-mapping user/conductor user/filter-scheduler @@ -155,7 +124,6 @@ Open Development. reference/i18n reference/notifications user/placement - contributor/placement user/quotas reference/threading reference/vm-states @@ -177,23 +145,10 @@ these are a great place to start reading up on the current plans. user/cells user/cellsv2_layout user/upgrade - contributor/api - contributor/microversions reference/policy-enforcement reference/stable-api reference/scheduler-evolution -Advanced testing and guides ----------------------------- - -.. toctree:: - :maxdepth: 1 - - reference/gmr - contributor/testing/libvirt-numa - contributor/testing/serial-console - contributor/testing/zero-downtime-upgrade - Configuration ------------- @@ -235,6 +190,24 @@ Module Reference .. toctree:: :hidden: + contributor/development-environment + reference/gmr + contributor/api + contributor/api-2 + contributor/blueprints + contributor/code-review + contributor/microversions + contributor/placement.rst + contributor/policies.rst + contributor/releasenotes + contributor/testing + contributor/testing/libvirt-numa + contributor/testing/serial-console + contributor/testing/zero-downtime-upgrade + contributor/how-to-get-involved + contributor/process + contributor/project-scope + Installation Guide ==================