Merge "Evolve project setup into a tech guidance chapter"

This commit is contained in:
Zuul 2018-07-19 18:03:32 +00:00 committed by Gerrit Code Review
commit 80acf5cd74
4 changed files with 53 additions and 13 deletions

View File

@ -0,0 +1 @@
redirectmatch 301 ^/project-team-guide/project-setup.html$ /project-team-guide/technical-guidance.html

View File

@ -96,6 +96,10 @@ man_pages = []
# -- Options for HTML output ---------------------------------------------------
# Add any paths that contain "extra" files, such as .htaccess or
# robots.txt.
html_extra_path = ['_extra']
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#html_theme = 'nature'

View File

@ -25,7 +25,7 @@ Contents:
bugs
vulnerability-management
dependency-management
project-setup
technical-guidance
testing
oslo
documentation

View File

@ -1,6 +1,47 @@
=============
Project Setup
=============
=========================================
Technical Guidance for OpenStack projects
=========================================
This chapter contains basic technical guidelines to help you design and set
up an OpenStack project.
This content is aspirational, and not prescriptive - while working towards a
universally consistent technical design is laudable, it is often impractical,
given technical debt, architectural decisions, and project constraints.
Base services
-------------
OpenStack services rely on external services to deliver their functionality.
Base services are external services that OpenStack components can assume
will be present in any OpenStack deployment. OpenStack components may
therefore leverage advanced features exposed by those base services without
needing to reimplement the wheel locally.
The Technical Committee maintains the `list of base services`_.
The Technical Committee constantly considers new additions to the list,
conservatively weighing the benefit of that service against the additional
operational cost for OpenStack deployers.
.. _list of base services: https://governance.openstack.org/tc/reference/base-services.html
API guidelines
--------------
We strive to improve the experience of API end users by converging the
OpenStack API to a consistent and pragmatic RESTful design. The
`API SIG`_ maintains a `set of API guidelines`_ to that effect.
.. _API SIG: http://specs.openstack.org/openstack/api-wg
.. _set of API guidelines: http://specs.openstack.org/openstack/api-wg/#guidelines
Best practices for project setup
--------------------------------
OpenStack has many projects, so many that contributor usability is a
serious concern. The harder it is to get from a fresh source tree to a
@ -8,17 +49,11 @@ contribution, the more difficult it becomes to develop a complex,
multi-service feature. A consistent project setup reduces this friction, both
for new contributors and for seasoned ones.
This chapter addresses common tools, libraries, and approaches, used in the
This section addresses common tools, libraries, and approaches, used in the
OpenStack ecosystem. It begins where the `Consistent Testing Interface`_
ends, by explaining guidelines, best practices, lessons learned, and answers
to frequently asked questions.
This content is aspirational, and not prescriptive - while working towards a
universally consistent project setup is laudable, it is often impractical,
given technical debt, architectural decisions, and project constraints.
Best Practices
--------------
Avoid multi-language projects
=============================
@ -49,8 +84,8 @@ on a library, it will automatically receive patch requests whenever that
particular library is updated. This also permits us to globally freeze our
dependencies in anticipation of a release.
Language-specific Guides
------------------------
Follow language-specific Guides
===============================
For a guide for a specific language, please choose the appropriate article
below.