9fd03c71c7
This updates as many references to 'API-WG', 'API Working Group', etc., to reflect the name change to the API-SIG. Change-Id: I15ca0860c58bd7ba51f08dd39e551a774d7a060a
95 lines
2.8 KiB
ReStructuredText
95 lines
2.8 KiB
ReStructuredText
..
|
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
|
License.
|
|
|
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
|
|
|
..
|
|
The title of your guideline should replace the
|
|
"Example Guideline Category"
|
|
|
|
==========================
|
|
Example Guideline Category
|
|
==========================
|
|
|
|
Introduction paragraph -- what does this guideline category address? A single
|
|
paragraph of prose that implementors can understand. This paragraph should
|
|
describe the intent and scope of the guideline. The title and this first
|
|
paragraph should be used as the subject line and body of the commit message
|
|
respectively.
|
|
|
|
Some notes about using this template:
|
|
|
|
* Your guideline should be in ReSTructured text, like this template.
|
|
|
|
* Please wrap text at 79 columns.
|
|
|
|
* For help with syntax, see http://sphinx-doc.org/rest.html
|
|
|
|
* To test out your formatting, build the docs using tox, or see:
|
|
http://rst.ninjs.org
|
|
|
|
* For help with OpenStack documentation conventions, see
|
|
https://wiki.openstack.org/wiki/Documentation/Conventions
|
|
|
|
Each file should be a group of related guidelines, such as "HTTP Headers" or
|
|
similar. Each guideline gets its own subheader, and within each section there
|
|
is an overview/introduction, a guidance section, examples, and references. Not
|
|
every guideline will fill in every section. If a section isn't needed for a
|
|
particular guideline, delete it if you're **really** sure it's superfluous.
|
|
|
|
Guideline Name
|
|
--------------
|
|
|
|
A detailed guideline that is being suggested. It should also have an
|
|
introduction if applicable.
|
|
|
|
Guidance
|
|
********
|
|
|
|
The actual guidance that the API Special Interest Group would like to provide.
|
|
|
|
* The guideline should provide a clear recitation of the actions to be
|
|
taken by implementors.
|
|
|
|
* Reference to specific technology implementations (for example,
|
|
XXX-Y.Z package) should be avoided.
|
|
|
|
* External references should be described by annotations with the
|
|
links to the source material in the References section. (for example,
|
|
please see :rfc:`0000` or this footnote guide [#f1]_)
|
|
|
|
Examples
|
|
********
|
|
|
|
A series of examples that demonstrate the proper usage of the guideline
|
|
being proposed. These examples may include, but are not limited to:
|
|
|
|
* JSON objects.
|
|
|
|
* HTTP methods demonstrating requests and responses.
|
|
|
|
The examples should not include:
|
|
|
|
* Code samples designed for implementation.
|
|
|
|
References
|
|
**********
|
|
|
|
References may be provided in cases where they aid in giving a more complete
|
|
understanding of the guideline. You are not required to have any references.
|
|
Moreover, this guideline should still make sense when your references are
|
|
unavailable. Examples of what you could include are:
|
|
|
|
* Links to mailing list or IRC discussions
|
|
|
|
* Links to notes from a summit session
|
|
|
|
* Links to relevant research, if appropriate
|
|
|
|
RST supports footnotes in the following format:
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#f1] http://sphinx-doc.org/rest.html#footnotes
|