88 lines
3.3 KiB
ReStructuredText
88 lines
3.3 KiB
ReStructuredText
=========
|
|
DocImpact
|
|
=========
|
|
|
|
When adding code that affects documentation (for example, to add a new
|
|
parameter), the developer adds a DocImpact flag.
|
|
|
|
Using the DocImpact flag in a commit message
|
|
--------------------------------------------
|
|
|
|
In any OpenStack project, you can add a ``DocImpact`` flag in a commit message
|
|
to help identify any bugs that require documentation to be written
|
|
in the OpenStack manuals project.
|
|
|
|
This method offers notification and tracking of the possible impact to
|
|
documentation due to the patch. If your commit has an impact on
|
|
documentation, for example an added, altered, or removed command line option,
|
|
a deprecated or new feature, a caveat or if you have written docs in the patch,
|
|
add "DocImpact" to a line in your commit message.
|
|
|
|
This creates a Launchpad bug for the project indicated in the
|
|
``gerrit/projects.yaml`` file in the `openstack/project-config
|
|
<https://opendev.org/openstack/project-config>`_ repository.
|
|
This does not guarantee documentation will be written, but offers visibility of
|
|
the change and tracking. You can also use it as a reminder to yourself to write
|
|
docs for the feature later, or remind yourself to find a writer to write for
|
|
you.
|
|
|
|
If you are a doc contributor, these are the steps we take once a ``DocImpact``
|
|
notification comes to the list.
|
|
|
|
#. Create a new doc bug in either ``openstack-manuals`` or
|
|
``openstack-api-site``.
|
|
In the bug:
|
|
|
|
#. In the title, put ``newton`` or ``ocata`` depending on the release the
|
|
patch affects.
|
|
#. Copy and paste the ``review.opendev.org`` link in the bug description.
|
|
#. Describe the documentation that is affected if the code patch lands in
|
|
the bug description.
|
|
#. Keep the doc bug set to ``New`` until the code patch is merged.
|
|
|
|
#. Continue to check on the patch and change the status to ``Confirmed`` once
|
|
merged.
|
|
|
|
#. Use the information in the :ref:`guidelines` section to set priority once it
|
|
lands.
|
|
|
|
Writing good commit messages for DocImpact
|
|
------------------------------------------
|
|
|
|
Because the entire commit message is included in the logged bug, try to put
|
|
as much information as you can into the commit message about which doc audience
|
|
is affected by the change or enhancement, what the change is and why it
|
|
matters.
|
|
Answer the following questions when writing the commit message:
|
|
|
|
* Who would use the feature?
|
|
|
|
* Why use the feature?
|
|
|
|
* What is the exact usage for the feature? If it's an API change,
|
|
give example requests and responses.
|
|
|
|
* Does the feature also have permissions/policies attached? If so, what are
|
|
the requirements?
|
|
|
|
If it is a configuration option change, our automation will pick it up.
|
|
However, we do request for individually filed bugs outside of the automated
|
|
generation.
|
|
|
|
If it is a CLI change, we also have automation that picks up the help text,
|
|
but extra usage information is useful.
|
|
|
|
Third-Party DocImpact settings
|
|
------------------------------
|
|
|
|
By default, the ``DocImpact`` tag creates bugs using the repository name as
|
|
project in Launchpad. To change this behavior, the ``docimpact-group`` option
|
|
in ``projects.yaml`` can be used. For example, if you set project like this:
|
|
|
|
.. code-block:: yaml
|
|
|
|
- project: stackforge/project-name
|
|
description: Latest and greatest cloud stuff.
|
|
upstream: git://github.com/awesumsauce/project-name.git
|
|
docimpact-group: Project
|