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