openstack
/
governance
Code Issues Proposed changes

Fix format errors in PTI docs 

Extra spaces and unnecessary tags are causing sections to be block
quoted and other incorrect formatting in the rendered output.

Change-Id: Ibe3d35e6983febe4171a0f282e2016d342f2a817
Signed-off-by: Sean McGinnis <sean.mcginnis@gmail.com>
This commit is contained in:
Sean McGinnis 2018-10-16 11:58:30 -05:00
parent b635df1cd0
commit 8ca967a7fd
No known key found for this signature in database
GPG Key ID: CE7EE4BFAF8D70C8
3 changed files with 117 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
reference/pti/golang.rst
View File

@ -14,13 +14,13 @@ and they follow OpenStack processes where feasible.
Each golang project must be able to do:
- Dependency installation
- Code style checks
- Unit tests
- Functional tests
- Test Coverage Report
- Documentation generation
- Translations import/export and merge for translated projects
- Dependency installation
- Code style checks
- Unit tests
- Functional tests
- Test Coverage Report
- Documentation generation
- Translations import/export and merge for translated projects
There is not yet a consensus among the to golang community for build
and package management tools as the ``go`` tool itself was intended to
@ -41,40 +41,40 @@ Specific commands
To drive the above tasks, the following commands should be supported in
a clean tree:
:code:`make depend`
Install dependencies required to build the project
``make depend``
Install dependencies required to build the project
:code:`make build`
Execute build process
``make build``
Execute build process
:code:`make install`
Execute binary install
``make install``
Execute binary install
:code:`make test`
Execute tests
``make test``
Execute tests
:code:`make fmt`
Execute code style checks
``make fmt``
Execute code style checks
:code:`make docs`
Generate HTML documentation from the in-tree developer docs
``make docs``
Generate HTML documentation from the in-tree developer docs
:code:`make godoc`
Generate the golang docs from the source
``make godoc``
Generate the golang docs from the source
:code:`make releasenotes`
Generate HTML release notes
``make releasenotes``
Generate HTML release notes
Additional commands may be supported, but are not required:
:code:`make cover`
Generate coverage reports
``make cover``
Generate coverage reports
:code:`make lint`
Execute more code style checks
``make lint``
Execute more code style checks
:code:`make translation`
Perform translation-related tasks (TBD)
``make translation``
Perform translation-related tasks (TBD)
Project Setup
-------------
@ -82,24 +82,25 @@ Project Setup
Project repos shall use a structure that is a hybrid of the typical OpenStack
structure and those commonly found in the golang community. Because
these are OpenStack projects, the top-level structure shall contain
the existing process-related components. All golang source code and modules shall
be in one or more subdirectories named in a manner to identify its contents
distinctly from the Python namespace directories currently used.
the existing process-related components. All golang source code and modules
shall be in one or more subdirectories named in a manner to identify its
contents distinctly from the Python namespace directories currently used.
This allows the golang code to maintain its native style and not be
mixed in with the OpenStack tool-related pieces such as Sphinx documentation
and Reno release notes.
The source subdirectory naming is intentionally flexible in order to
accommodate unforeseen situations, however the following guidelines should
be strongly considered::
be strongly considered:
- Simple projects or projects that only need one golang workspace can use
a single top-level directory named ``go``.
- Projects that may have multiple distinct golang workspaces should use
names that include a ``-go`` suffix. This allows similarly named modules
in multiple languages to co-exist. For example: the CloudTool project
should continue to put Python sources in its Python namespace ``cloudtool``
and the golang source in ``cloudtool-go`` (do not use a period!).
- Simple projects or projects that only need one golang workspace can use
a single top-level directory named ``go``.
- Projects that may have multiple distinct golang workspaces should use
names that include a ``-go`` suffix. This allows similarly named modules
in multiple languages to co-exist. For example: the CloudTool project
should continue to put Python sources in its Python namespace ``cloudtool``
and the golang source in ``cloudtool-go`` (do not use a period!).
Dependency Management
---------------------
@ -108,8 +109,8 @@ OpenStack has chosen to use Glide_ as the common dependency management tool
for golang. The ``depend`` target provides a common interface to Glide's
``install`` command.
:code:`make depend`
Install dependencies required to build the project
``make depend``
Install dependencies required to build the project
Golang dependencies shall not be vendored in golang repos. Each project shall
include a list of its dependencies and acceptable/tested versions in the repo.
@ -144,11 +145,11 @@ other operations such as ``go test``. Build and install are split out here
as they are common operations and useful in their own right. These targets
are not strictly necessary for CI testing.
:code:`make build`
Execute build process
``make build``
Execute build process
:code:`make install`
Execute binary install
``make install``
Execute binary install
Codestyle Checks
----------------
@ -159,12 +160,12 @@ target shall not use ``go fmt`` which rewrites source files by default.
As a developer convenience a second target called ``fmtfix`` shall be
defined that does the source fixups (equivalent to ``gofmt -l -w``).
:code:`make fmt`
Run the gofmt tool non-destructively to validate code formatting
``make fmt``
Run the gofmt tool non-destructively to validate code formatting
:code:`make fmtfix`
Run the gofmt tool and overwrite source files with gofmt's version
if changes are required. This is primarily a developer convenience.
``make fmtfix``
Run the gofmt tool and overwrite source files with gofmt's version
if changes are required. This is primarily a developer convenience.
Tests
-----
@ -172,8 +173,8 @@ Tests
OpenStack uses ``go test`` to run all test types at once invoked via
the ``Makefile``.
:code:`make test`
Run tests
``make test``
Run tests
This is the general test target and may simply call some subset of additional
``test-*`` targets. Specific test targets should be named with a ``test-*``
@ -203,8 +204,8 @@ Sphinx to generate our Narrative Project documentation.
In addition to the normal PTI :ref:`pti-documentation` requirements, for
developer convenience, Go projects are recommended to provide:
:code:`make docs`
Generate HTML documentation from the in-tree developer docs
``make docs``
Generate HTML documentation from the in-tree developer docs
that should:
@ -220,8 +221,8 @@ Go has a well-defined documentation tool `godoc`_ that produces
developer documentation extracted from source code comments, similar to
Python's Docstring.
:code:`make godoc`
Generate the golang docs from the source
``make godoc``
Generate the golang docs from the source
.. TBD(dtroyer): define how the godoc output is integrated with the current
.. sphinx process
@ -237,8 +238,8 @@ the final HTML documentation.
In addition to the normal PTI :ref:`pti-documentation` requirements, for
developer convenience, Go projects are recommended to provide:
:code:`make releasenotes`
Generate HTML release notes
``make releasenotes``
Generate HTML release notes
Translations
------------

79
reference/pti/javascript.rst
View File

@ -5,23 +5,23 @@ Project Testing Interface: JavaScript
This document outlines common ways to meet the Project Testing Interface
requirements for JavaScript. Each JavaScript project must be able to do:
- Codestyle checks.
- Execute Tests and Code Coverage
- Package Tarball Generation
- Documentation Generation
- Validate dependency licenses
- Codestyle checks.
- Execute Tests and Code Coverage
- Package Tarball Generation
- Documentation Generation
- Validate dependency licenses
Projects which are browser based must also be able to do:
- Unit tests in Firefox and Chromium.
- Unit tests in Firefox and Chromium.
Projects which are server based must also be able to do:
- Unit tests in Node.js.
- Unit tests in Node.js.
Projects which require translation must also be able to do:
- Translation import/export and merge for translated objects.
- Translation import/export and merge for translated objects.
Specific commands
-----------------
@ -29,31 +29,31 @@ Specific commands
The following commands must be supported at the root of a clean tree, in
order to initialize your project.
:code:`npm install`
``npm install``
This command installs all of the project's dependencies.
To drive the above required steps, the following commands should be
supported at the root of an initialized tree.
:code:`npm test`
``npm test``
This command executes all available test suites, and generate
appropriate code coverage reports.
:code:`npm run lint`
``npm run lint``
This command performs codestyle checks against the project.
:code:`npm pack`
``npm pack``
This command generates a release tarball.
:code:`npm publish <tarball> --no-scripts`
``npm publish <tarball>--no-scripts``
This command will publish a release tarball to npm. It may not be
necessary for all projects.
:code:`npm run document`
``npm run document``
This command builds documentation for the project.
The following commands are still under discussion:
:code:`npm run license`
``npm run license``
This command ensures that no incompatible licenses have accidentally been
included.
:code:`npm run translate`
``npm run translate``
This command imports translations into this project, if necessary.
@ -80,13 +80,13 @@ Requirements Listing
Each project should list its runtime, peer, and development dependencies
in package.json and (if applicable) bower.json.
:code:`dependencies`
``dependencies``
Packages required by your project to run in production. These should
never use fuzzy version matching.
:code:`devDependencies`
``devDependencies``
Packages that are required by your project during the test and build
phase. These should never use fuzzy version matching.
:code:`peerDependencies`
``peerDependencies``
Packages that are used to run your project, but whose version does not
strictly matter. For example, eslint-config-openstack has eslint as a
peer dependency.
@ -104,7 +104,7 @@ expected output.
Codestyle Checks
================
:Command: :code:`npm run lint`
:Command: ``npm run lint``
OpenStack requires the custom npm script 'lint' to execute our codestyle
checks. The tool we use is called `ESLint`_, and our rules are published to npm
@ -112,69 +112,70 @@ as eslint-config-openstack_.
Executing Tests and Code Coverage
=================================
:Command: :code:`npm test`
:Command: ``npm test``
OpenStack requires a sane testing and code coverage strategy for each
project, though we do not prescribe the tools and coverage threshold, as
these may differ based on circumstance and project type. Generated test
reports should be placed in :code:`./reports` in your projects' root directory.
Generated coverage output should similarly be placed in :code:`./cover`.
reports should be placed in `./reports` in your projects' root directory.
Generated coverage output should similarly be placed in `./cover`.
Package Tarball Generation
==========================
:Command: :code:`npm pack`
:Command: ``npm pack``
OpenStack uses :code:`npm pack` to generate a release tarball, which will
compile all files listed in :code:`package.json`. If your project requires
OpenStack uses ``npm pack`` to generate a release tarball, which will
compile all files listed in `package.json`. If your project requires
concatenation, minification, or any other preprocessing to create a valid
tarball, you may use the npm :code:`prepublish` hook to trigger these steps.
tarball, you may use the npm `prepublish` hook to trigger these steps.
All packages should include:
- A README
- A LICENSE file
- All source code
- A README
- A LICENSE file
- All source code
Generate Documentation
======================
:Command: :code:`npm run document`
:Command: ``npm run document``
In order to reuse existing templates, styles, and tooling, OpenStack uses
Sphinx to generate our JavaScript Project documentation.
In addition to the normal PTI :ref:`pti-documentation` requirements, Javascript
projects are recommended to provide an :code:`npm run document` command for
projects are recommended to provide an `npm run document` command for
developer convenience that should:
* Either install any needed distro dependencies from the ``doc`` tag in
``bindep.txt`` or emit an error if they are not installed.
* Install Python dependencies for Sphinx from ``doc/requirements.txt``.
* Execute ``sphinx-build -b html doc/source doc/build``
* Execute ``sphinx-build-b html doc/source doc/build``
The project infrastructure will not use ``npm`` to build the documentation.
Therefore it is **STRONGLY** discouraged for people to put additional logic
into the :code:`npm run document` command. Additional logic needed around
into the `npm run document` command. Additional logic needed around
Sphinx generation should go into Sphinx plugins which should be listed in
``doc/requirements.txt``.
Generate Release Notes
======================
:Command: :code:`npm run releasenotes`
:Command: ``npm run releasenotes``
OpenStack uses `reno <https://docs.openstack.org/reno/latest/>`_ for generating
release notes.
In addition to the normal PTI :ref:`pti-documentation` requirements, Javascript
projects are recommended to provide an :code:`npm run releasenotes` command for
projects are recommended to provide an `npm run releasenotes` command for
developer convenience that should:
* Either install any needed distro dependencies from the ``releasenotes`` tag
in ``bindep.txt`` or emit an error if they are not installed.
* Execute: ``sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html``
* Execute: ``sphinx-build -a -E -W -d releasenotes/build/doctrees-b html
releasenotes/source releasenotes/build/html``
The project infrastructure will not use :code:`npm run releasenotes` to build
The project infrastructure will not use `npm run releasenotes` to build
the release notes. Therefore it is **STRONGLY** discouraged for people to put
additional logic into the :code:`npm run releasenotes` command. Additional
additional logic into the `npm run releasenotes` command. Additional
logic needed should go into reno.
.. _NPM package scripts: https://docs.npmjs.com/misc/scripts

34
reference/pti/python.rst
View File

@ -6,16 +6,16 @@ Project Testing Interface: Python
Each python project must be able to do:
- Unit tests for python2.7
- Codestyle checks
- Testing Coverage Report
- Source Tarball Generation
- Translations import/export and merge for translated projects
- Documentation generation
- Unit tests for python2.7
- Codestyle checks
- Testing Coverage Report
- Source Tarball Generation
- Translations import/export and merge for translated projects
- Documentation generation
Projects which are compatible with Python 3 must also be able to do:
- Unit tests for python3.5
- Unit tests for python3.5
Specific commands
-----------------
@ -23,21 +23,21 @@ Specific commands
To drive the above tasks, the following commands should be supported in a clean
tree:
- tox -epy27
- tox -epep8
- tox -ecover
- python setup.py sdist
- python setup.py bdist_wheel
- sphinx-build -W -b html doc/source doc/build
- ``tox -e py27``
- ``tox -e pep8``
- ``tox -e cover``
- ``python setup.py sdist``
- ``python setup.py bdist_wheel``
- ``sphinx-build -W -b html doc/source doc/build``
Projects that are translated should also support:
- tox -evenv python setup.py extract_messages
- tox -evenv python setup.py update_catalog
- ``tox -e venv python setup.py extract_messages``
- ``tox -e venv python setup.py update_catalog``
Projects which are compatible with Python 3 must also be able to do:
- tox -epy35
- ``tox -e py35``
Some basic prerequisites for test running (system packages, database
configuration, custom filesystem types) are acceptable as long as they are
@ -159,7 +159,7 @@ a ``releasenotes`` environment for tox that will run
sphinx-build -a -E -W -d releasenotes/build/doctrees -b html \
releasenotes/source releasenotes/build/html
The project infrastructure will not use ``tox -ereleasenotes`` to build the
The project infrastructure will not use ``tox -e releasenotes`` to build the
documentation. Therefore it is **STRONGLY** discouraged for people to put
additional logic into the command section of that tox environment. Additional
logic needed around releasenotes generation should go into reno.