From ba41eb0c7ae370aa57c8a7b43e705dda1cea4d71 Mon Sep 17 00:00:00 2001 From: Ghanshyam Mann Date: Tue, 22 Mar 2022 20:20:49 -0500 Subject: [PATCH] Move technical-guidance.rst under technical-guides We have new directory technical-guides which include the new guidlines unified limits. We can move the existing file technical-guidance.rst also under the same dir to avoid any confusion. Change-Id: Ibe9facc4518b1f1317579373b40a5e63f89d2240 --- doc/source/_extra/.htaccess | 1 + doc/source/index.rst | 1 - .../best-practices-for-project-setup.rst | 58 +++---------------- technical-guides/index.rst | 45 ++++++++++++++ 4 files changed, 54 insertions(+), 51 deletions(-) rename doc/source/technical-guidance.rst => technical-guides/best-practices-for-project-setup.rst (56%) diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess index a904aaa..a22c43e 100644 --- a/doc/source/_extra/.htaccess +++ b/doc/source/_extra/.htaccess @@ -1 +1,2 @@ redirectmatch 301 ^/project-team-guide/project-setup.html$ /project-team-guide/technical-guidance.html +redirectmatch 301 ^/project-team-guide/technical-guidance.html$ /project-team-guide/technical-guides/index.html diff --git a/doc/source/index.rst b/doc/source/index.rst index f3ba40d..3b8dd17 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -27,7 +27,6 @@ Contents: bugs vulnerability-management dependency-management - technical-guidance testing oslo documentation diff --git a/doc/source/technical-guidance.rst b/technical-guides/best-practices-for-project-setup.rst similarity index 56% rename from doc/source/technical-guidance.rst rename to technical-guides/best-practices-for-project-setup.rst index f9a640b..ae5381a 100644 --- a/doc/source/technical-guidance.rst +++ b/technical-guides/best-practices-for-project-setup.rst @@ -1,47 +1,6 @@ -========================================= -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 @@ -49,14 +8,13 @@ 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 section addresses common tools, libraries, and approaches, used in the +This document 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. - Avoid multi-language projects -============================= +----------------------------- Every programming language has established solid, reliable tooling for itself, based on assumptions that are relevant only to itself. These assumptions rarely translate well between different languages, and thus any @@ -76,7 +34,7 @@ project, while providing documentation that explains how these projects are integrated. Subscribe to Global Dependencies -================================ +-------------------------------- OpenStack maintains a list of global dependencies, and their version constraints, in order to ensure that peer libraries operate as expected. This is done in an as-needed basis: If your project declares that it is dependent @@ -85,7 +43,7 @@ particular library is updated. This also permits us to globally freeze our dependencies in anticipation of a release. Follow language-specific Guides -=============================== +------------------------------- For a guide for a specific language, please choose the appropriate article below. @@ -93,7 +51,7 @@ below. .. toctree:: :maxdepth: 1 - Python - JavaScript + Python<../project-setup/python> + JavaScript<../project-setup/javascript> .. _Consistent Testing Interface: https://governance.openstack.org/tc/reference/project-testing-interface.html diff --git a/technical-guides/index.rst b/technical-guides/index.rst index 606854b..8d64f39 100644 --- a/technical-guides/index.rst +++ b/technical-guides/index.rst @@ -2,7 +2,52 @@ Technical Guides ================ +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. + +Using Unified Limits +-------------------- .. toctree:: :maxdepth: 2 unified-limits + +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 +-------------------------------- +.. toctree:: + :maxdepth: 2 + + best-practices-for-project-setup