Merge "Evolve project setup into a tech guidance chapter"
This commit is contained in:
commit
80acf5cd74
1
doc/source/_extra/.htaccess
Normal file
1
doc/source/_extra/.htaccess
Normal file
@ -0,0 +1 @@
|
||||
redirectmatch 301 ^/project-team-guide/project-setup.html$ /project-team-guide/technical-guidance.html
|
@ -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'
|
||||
|
@ -25,7 +25,7 @@ Contents:
|
||||
bugs
|
||||
vulnerability-management
|
||||
dependency-management
|
||||
project-setup
|
||||
technical-guidance
|
||||
testing
|
||||
oslo
|
||||
documentation
|
||||
|
@ -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.
|
Loading…
Reference in New Issue
Block a user