openstack/glance
Code Issues Proposed changes
glance/doc/source/contributing/documentation.rst
Niall Bunting 4f61f951fd Add documentation about generating release notes 
This adds a section about generating release notes to the glance
documentation. So we can point people there if they need to add
some release notes to their patch.

Change-Id: I5756fcc6ff10cf88a2f3ad679f2e565a3c173a93
2016-06-21 10:02:24 +00:00

2.5 KiB
Raw Blame History

Documentation

There are a few different kinds of documentation associated with Glance to which you may want to contribute:

  • Configuration

    As you read through the sample configuration files in the etc directory in the source tree, you may find typographical errors, or grammatical problems, or text that could use clarification. The Glance team welcomes your contributions, but please note that the sample configuration files are generated, not static text. Thus you must modify the source code where the particular option you're correcting is defined and then re-generate the conf file using tox -e genconfig.

  • Glance's Documentation

    The Glance Documentation (what you're reading right now) lives in the source code tree under doc/source. It consists of information for developers working on Glance, information for consumers of the OpenStack Images APIs implemented by Glance, and information for operators deploying Glance. Thus there's a wide range of documents to which you could contribute.

    Small improvements can simply be addressed by a patch, but it's probably a good idea to first file a bug for larger changes so they can be tracked more easily (especially if you plan to submit several different patches to address the shortcoming).

  • User Guides

    There are several user guides published by the OpenStack Documentation Team. Please see the README in their code repository for more information: https://github.com/openstack/openstack-manuals

  • OpenStack API Reference

    There are some Glance-related API quick-reference guides published by the OpenStack Documentation Team. Please see the README in their code repository for more information: https://github.com/openstack/api-site

Release Notes

Release notes are notes available for operators to get an idea what each project has included and changed during a cycle. They may also include various warnings and notices.

Generating release notes is done with Reno.

$ tox -e venv -- reno new <bug-,bp-,whatever>

This will generate a yaml file in releasenotes/notes that will contain instructions about how to fill in (or remove) the various sections of the document. Modify the yaml file as appropriate and include it as part of your commit.

Once the release notes have been committed you can build them by using:

$ tox -e releasenotes

This will create the HTML files under releasenotes/build/html/.