Merge "Remove DocImpact info from contributor docs"

doc/source/contributor/contribute.rst

@@ -274,6 +274,13 @@ uses them. For more details see `devstack-vm-gate-wrap.sh
 <https://git.openstack.org/cgit/openstack-infra/devstack-gate/tree/devstack-vm-gate-wrap.sh>`_.
 
 
+Documentation
+-------------
+
+For a layout of the how the documentation directory is structured see the
+`effective neutron guide <effective_neutron.html>`_
+
+
 Project Initial Setup
 ---------------------
 

doc/source/contributor/effective_neutron.rst

@@ -288,6 +288,25 @@ For anything more elaborate, please visit the testing section.
   consider using `OpenFixture <https://review.openstack.org/#/c/232716/>`_, 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.

doc/source/contributor/policies/blueprints.rst

@@ -298,6 +298,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.

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".
 

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 <http://devstack.org/>`_ or `NeutronDevstack <https://wiki.openstack.org/wiki/NeutronDevstack#Basic_Setup>`_
 for more information on using Neutron with devstack.
 
-Helping with documentation can also be a useful first step for a newcomer. `Here <https://bugs.launchpad.net/openstack-manuals/+bugs?field.tag=neutron>`_
-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 <https://bugs.launchpad.net/neutron/+bugs?field.tag=doc>`_
+* `Api-ref bugs <https://bugs.launchpad.net/neutron/+bugs?field.tag=api-ref>`_
 
 IRC Information and Etiquette
 -----------------------------