Merge "Add Golang CTI"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
e879d3e0cf
258
reference/cti/golang_cti.rst
Normal file
258
reference/cti/golang_cti.rst
Normal file
@ -0,0 +1,258 @@
|
||||
================================
|
||||
Consistent Testing Interface: Go
|
||||
================================
|
||||
|
||||
Go language (golang) repositories shall use the following interface
|
||||
for testing and automation purposes. This includes both pure golang
|
||||
repos and mixed-language repos as some of the OpenStack tooling defined
|
||||
for Python repos is re-used here.
|
||||
|
||||
A major criteria here is to not create an environment that is totally
|
||||
foreign to what developers are accustomed to in their respective
|
||||
communities. Remember these are first OpenStack projects
|
||||
and they follow OpenStack processes where feasable.
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
be sufficient. The traditional ``make(1)`` command is often used to
|
||||
supplement this role and provide the sort of interface that is common
|
||||
in many languages.
|
||||
|
||||
OpenStack has adopted the practice of using ``make`` for golang CTI as
|
||||
it provides a similar role fulfilled by ``tox`` in Python projects. It
|
||||
is also possible (and highly recommended) to use make to proxy tox or
|
||||
tox to proxy make in a mixed-language repo. Both tools use files that
|
||||
should remain transparent enough to most developers to understand what
|
||||
operations are actually being performed.
|
||||
|
||||
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
|
||||
|
||||
:code:`make build`
|
||||
Execute build process
|
||||
|
||||
:code:`make install`
|
||||
Execute binary install
|
||||
|
||||
:code:`make test`
|
||||
Execute tests
|
||||
|
||||
:code:`make fmt`
|
||||
Execute code style checks
|
||||
|
||||
:code:`make docs`
|
||||
Generate HTML documentation from the in-tree developer docs
|
||||
|
||||
:code:`make godoc`
|
||||
Generate the golang docs from the source
|
||||
|
||||
:code:`make releasenotes`
|
||||
Generate HTML release notes
|
||||
|
||||
Additional commands may be supported, but are not required:
|
||||
|
||||
:code:`make cover`
|
||||
Generate coverage reports
|
||||
|
||||
:code:`make lint`
|
||||
Execute more code style checks
|
||||
|
||||
:code:`make translation`
|
||||
Perform translation-related tasks (TBD)
|
||||
|
||||
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.
|
||||
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::
|
||||
|
||||
- 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
|
||||
---------------------
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
The required dependencies shall be installed into a golang workspace compatible
|
||||
with the results of running ``go get``.
|
||||
|
||||
Dependencies are specified in golang via full paths of the form
|
||||
``git.openstack.org/openstack/golang-client``. All dependencies that are
|
||||
OpenStack projects will be required to use the ``git.openstack.org`` host
|
||||
in order for cross-repo dependencies to work properly under Zuul, and to
|
||||
minimize unnecessary mirrors.
|
||||
|
||||
To support OpenStack CI and to ensure the Depends-On footers work properly,
|
||||
this target must not modify existing git repo state for a given dependency
|
||||
if the git repository is already present in ``${GOPATH}/src/${repo}``. The
|
||||
CI system will pre-populate all necessary git repos that it knows about into
|
||||
the appropriate locations in the appropriate states.
|
||||
|
||||
External dependencies outside of the OpenStack CI should be installed as
|
||||
usual. It is expected that a mirror of required dependencies will be
|
||||
maintained in the CI system.
|
||||
|
||||
Further details will be included here as the dependency tooling is finalized.
|
||||
|
||||
.. _Glide: https://glide.sh/
|
||||
|
||||
Build and Install
|
||||
-----------------
|
||||
|
||||
The golang toolchain automatically performs the build step when required by
|
||||
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
|
||||
|
||||
:code:`make install`
|
||||
Execute binary install
|
||||
|
||||
Codestyle Checks
|
||||
----------------
|
||||
|
||||
OpenStack uses ``gofmt`` directly to check for proper coding style.
|
||||
As we do not want to be making changes to the repo in CI the default
|
||||
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
|
||||
|
||||
: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.
|
||||
|
||||
Tests
|
||||
-----
|
||||
|
||||
OpenStack uses ``go test`` to run all test types at once invoked via
|
||||
the ``Makefile``.
|
||||
|
||||
:code:`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-*``
|
||||
prefix as a convention.
|
||||
|
||||
Go test output is not natively in a format consumable by subunit, however
|
||||
there is at least one tool available that can easily be made to support
|
||||
subunit.
|
||||
|
||||
Generated Files
|
||||
---------------
|
||||
|
||||
ChangeLog and AUTHORS files are generated at <TBD>.
|
||||
|
||||
``.mailmap`` files should exist where a developer has more than one email
|
||||
address or identity, and should map to the developer's canonical identity.
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
Developer Documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
OpenStack projects use Sphinx to produce project documentation from
|
||||
in-tree sources in ``doc/source`` and the HTML output in ``doc/build``.
|
||||
|
||||
:code:`make docs`
|
||||
Generate HTML documentation from the in-tree developer docs
|
||||
|
||||
If the project contains a ``setup.py`` file, it is expected that the ``docs``
|
||||
target will pass through to the equivalent to ``python setup.py build_sphinx``.
|
||||
If no ``setup.py`` is present the equivalent of ``make -f doc/Makefile html``
|
||||
will be executed.
|
||||
|
||||
Source
|
||||
~~~~~~
|
||||
|
||||
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
|
||||
|
||||
.. TBD(dtroyer): define how the godoc output is integrated with the current
|
||||
.. sphinx process
|
||||
|
||||
.. _godoc: https://blog.golang.org/godoc-documenting-go-code
|
||||
|
||||
Release notes
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
OpenStack uses Reno to manage release notes. This uses Sphinx to generate
|
||||
the final HTML documentation.
|
||||
|
||||
:code:`make releasenotes`
|
||||
Generate HTML release notes
|
||||
|
||||
Translations
|
||||
------------
|
||||
|
||||
A common translation process is not yet well-defined in the golang community.
|
||||
This section will be completed once a process is developed that is compatible
|
||||
with the existing OpenStack translation workflow.
|
||||
|
||||
Release Tools
|
||||
-------------
|
||||
|
||||
OpenStack release tooling uses ``setup.py`` as an interface for the release
|
||||
process. It is expected that golang projects will also use ``setup.py`` for
|
||||
some of its interface to these tools, however it may be desirable to investigate
|
||||
alternate interfaces if Sphinx docs are the only primary use otherwise.
|
||||
|
||||
Build Tools
|
||||
-----------
|
||||
|
||||
A number of the tools used by OpenStack projects are written in Python and
|
||||
require local developer installation. This is something that tox is very good
|
||||
at and shall be used to manage those tools in its local virtual environments.
|
||||
|
||||
These tools should all be Python 3 compatible so non-Python projects should use
|
||||
only Python 3 in their local virtual environments for tooling support.
|
||||
Loading…
Reference in New Issue
Block a user