diff --git a/doc/source/contributor/contribute.rst b/doc/source/contributor/contribute.rst index f74bcca206b..36b39a9c22d 100644 --- a/doc/source/contributor/contribute.rst +++ b/doc/source/contributor/contribute.rst @@ -274,6 +274,13 @@ uses them. For more details see `devstack-vm-gate-wrap.sh `_. +Documentation +------------- + +For a layout of the how the documentation directory is structured see the +`effective neutron guide `_ + + Project Initial Setup --------------------- diff --git a/doc/source/contributor/effective_neutron.rst b/doc/source/contributor/effective_neutron.rst index 1cd8e9477fa..bc850a5b8ce 100644 --- a/doc/source/contributor/effective_neutron.rst +++ b/doc/source/contributor/effective_neutron.rst @@ -288,6 +288,25 @@ For anything more elaborate, please visit the testing section. consider using `OpenFixture `_, but it is better not to mock open() at all. +Documentation +~~~~~~~~~~~~~ + +The documenation for Neutron that exists in this repository is broken +down into the following directories based on content: + +* doc/source/admin/ - feature-specific configuration documentation aimed + at operators. +* doc/source/configuration - stubs for auto-generated configuration files. + Only needs updating if new config files are added. +* doc/source/contributor/internals - developer documentation for lower-level + technical details. +* doc/source/contributor/policies - neutron team policies and best practices. +* doc/source/install - install-specific documentation for standing-up + network-enabled nodes. + +Additional documentation resides in the neutron-lib repository: + +* api-ref - API reference documentation for Neutron resource and API extensions. Backward compatibility ~~~~~~~~~~~~~~~~~~~~~~ @@ -461,7 +480,12 @@ This is the TL;DR version with the important points for committing to Neutron. * One liners are bad, unless the change is trivial. -* Remember to use DocImpact, APIImpact, UpgradeImpact appropriately. +* Use ``UpgradeImpact`` when the change could cause issues during the upgrade + from one version to the next. +* ``APIImpact`` should be used when the api-ref in neutron-lib must be updated + to reflect the change, and only as a last resort. Rather, the ideal workflow + includes submitting a corresponding neutron-lib api-ref change along with + the implementation, thereby removing the need to use ``APIImpact``. * Make sure the commit message doesn't have any spelling/grammar errors. This is the first thing reviewers read and they can be distracting enough to invite -1's. diff --git a/doc/source/contributor/policies/blueprints.rst b/doc/source/contributor/policies/blueprints.rst index 18c9b2490ba..3e643dc34be 100644 --- a/doc/source/contributor/policies/blueprints.rst +++ b/doc/source/contributor/policies/blueprints.rst @@ -290,6 +290,6 @@ Devref content should be added as part of the implementation of a new feature. Since the spec is not maintained after the feature is implemented, the devref should include a maintained version of the information from the spec. -If a feature requires OS docs (4), the commit message for the feature patch -shall include 'DocImpact'. If the feature is purely a developer facing thing, -(4) is not needed. +If a feature requires OS docs (4), the feature patch shall include the new, +or updated, documentation changes. If the feature is purely a developer +facing thing, (4) is not needed. diff --git a/doc/source/contributor/policies/bugs.rst b/doc/source/contributor/policies/bugs.rst index dfbdf81688e..ab52da18421 100644 --- a/doc/source/contributor/policies/bugs.rst +++ b/doc/source/contributor/policies/bugs.rst @@ -228,14 +228,15 @@ The process of bug triaging consists of the following steps: * Check if a bug was filed for a correct component (project). If not, either change the project or mark it as "Invalid". -* For bugs that affect documentation (including autogenerated DocImpact bugs) - proceed like this. If documentation affects +* For bugs that affect documentation proceed like this. If documentation + affects: - * the ReST API, add "openstack-api-site" to the affected projects. + * the ReST API, add the "api-ref" tag to the bug. * the OpenStack manuals, like the Networking Guide or the Configuration - Reference, add "openstack-manuals" to the affected projects. Tag the bug - for the appropriate guide, e.g. "networking-guide". Remove "neutron" from - the affected projects if it only affects "openstack-manuals". + Reference, create a patch for the affected files in the documentation + directory in this repository. For a layout of the how the documentation + directory is structured see the `effective neutron guide + <../effective_neutron.html>`_ * developer documentation (devref), set the bug to "Confirmed" for the project Neutron, otherwise set it to "Invalid". diff --git a/doc/source/contributor/policies/contributor-onboarding.rst b/doc/source/contributor/policies/contributor-onboarding.rst index 6c792bb786a..ff210cafce5 100644 --- a/doc/source/contributor/policies/contributor-onboarding.rst +++ b/doc/source/contributor/policies/contributor-onboarding.rst @@ -17,9 +17,11 @@ can actually run the code. Devstack is the usual convenient environment to setup an environment. See `devstack.org `_ or `NeutronDevstack `_ for more information on using Neutron with devstack. -Helping with documentation can also be a useful first step for a newcomer. `Here `_ -is a list of documentation bugs that are tagged with 'neutron'; bug reports are created -here for neutron reviews with a 'DocImpact' in the commit message. +Helping with documentation can also be a useful first step for a newcomer. +Here is a list of tagged documentation and API reference bugs: + +* `Documentation bugs `_ +* `Api-ref bugs `_ IRC Information and Etiquette -----------------------------