From 29573f8fbf4ecc2b12ed1983f40672aac19a397a Mon Sep 17 00:00:00 2001 From: Ghanshyam Mann Date: Fri, 14 May 2021 15:20:01 -0500 Subject: [PATCH] [ussuri][goal] Update contributor documentation This patch updates/adds the contributor documentation to follow the guidelines of the Ussuri cycle community goal[1]. [1] https://governance.openstack.org/tc/goals/selected/ussuri/project-ptl-and-contrib-docs.html Story: #2007236 Task: #38524 Change-Id: I41b6fa23569047c8ed877902989a5ebd20c0c189 --- CONTRIBUTING.rst | 23 ++--- doc/source/_extra/.htaccess | 6 +- doc/source/contributor/blueprints.rst | 84 ------------------- doc/source/contributor/contributing.rst | 47 +++++++++++ doc/source/contributor/index.rst | 17 +--- .../architecture.rst | 0 doc/source/developing_guides/blueprints.rst | 16 ++++ .../gmr.rst | 0 doc/source/developing_guides/index.rst | 26 ++++++ .../pluginguide.rst | 0 .../rally_on_gates.rst | 0 .../schedulerhints.rst | 0 .../supportstatus.rst | 0 doc/source/index.rst | 25 ++++-- .../operating_guides/scale_deployment.rst | 2 +- 15 files changed, 124 insertions(+), 122 deletions(-) delete mode 100644 doc/source/contributor/blueprints.rst create mode 100644 doc/source/contributor/contributing.rst rename doc/source/{contributor => developing_guides}/architecture.rst (100%) create mode 100644 doc/source/developing_guides/blueprints.rst rename doc/source/{contributor => developing_guides}/gmr.rst (100%) create mode 100644 doc/source/developing_guides/index.rst rename doc/source/{contributor => developing_guides}/pluginguide.rst (100%) rename doc/source/{contributor => developing_guides}/rally_on_gates.rst (100%) rename doc/source/{contributor => developing_guides}/schedulerhints.rst (100%) rename doc/source/{contributor => developing_guides}/supportstatus.rst (100%) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 09f4a70b23..8ccf6dd4be 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,16 +1,19 @@ -If you would like to contribute to the development of OpenStack, -you must follow the steps in this page: +The source repository for this project can be found at: - https://docs.openstack.org/infra/manual/developers.html + https://opendev.org/openstack/heat -Once those steps have been completed, changes to OpenStack -should be submitted for review via the Gerrit tool, following -the workflow documented at: +Pull requests submitted through GitHub are not monitored. - https://docs.openstack.org/infra/manual/developers.html#development-workflow +To start contributing to OpenStack, follow the steps in the contribution guide +to set up and use Gerrit: -Pull requests submitted through GitHub will be ignored. + https://docs.openstack.org/contributors/code-and-documentation/quick-start.html -Bugs should be filed on OpenStack Storyboard, not GitHub: +Bugs should be filed on Storyboard,: - https://storyboard.openstack.org/#!/project/989 + https://storyboard.openstack.org/#!/project/openstack/heat + +For more specific information about contributing to this repository, see the +heat contributor guide: + + https://docs.openstack.org/heat/latest/contributor/contributing.html diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess index 566b27e8ed..630df389f1 100644 --- a/doc/source/_extra/.htaccess +++ b/doc/source/_extra/.htaccess @@ -1,5 +1,5 @@ -redirectmatch 301 ^/heat/([^/]+)/(architecture|pluginguide|schedulerhints|gmr|supportstatus)\.html$ /heat/$1/contributor/$2.html -redirectmatch 301 ^/heat/([^/]+)/developing_guides/(index|architecture|pluginguide|schedulerhints|gmr|supportstatus)\.html$ /heat/$1/contributor/$2.html +redirectmatch 301 ^/heat/([^/]+)/(architecture|pluginguide|schedulerhints|gmr|supportstatus)\.html$ /heat/$1/developing_guides/$2.html redirectmatch 301 ^/heat/([^/]+)/(scale_deployment)\.html$ /heat/$1/operating_guides/$2.html redirectmatch 301 ^/heat/([^/]+)/configuration/(api|clients)\.html /heat/$1/configuration/config-options.html -redirectmatch 301 ^/heat/([^/]+)/contributing/(index|blueprints)\.html /heat/$1/contributor/$2.html +redirectmatch 301 ^/heat/([^/]+)/contributing/(index|blueprints)\.html /heat/$1/developing_guides/$2.html +redirectmatch 301 ^/heat/([^/]+)/contributor/(blueprints)\.html /heat/$1/developing_guides/$2.html diff --git a/doc/source/contributor/blueprints.rst b/doc/source/contributor/blueprints.rst deleted file mode 100644 index e8d7f74e07..0000000000 --- a/doc/source/contributor/blueprints.rst +++ /dev/null @@ -1,84 +0,0 @@ -Blueprints and Specs -==================== - -The Heat team uses the `heat-specs -`_ repository for its -specification reviews. Detailed information can be found `here -`_. - -Please note that we use a template for spec submissions. Please use the -`template for the latest release -`_. -It is not required to fill out all sections in the template. - -You have to create a Story in StoryBoard `heat storyboard -`_. And create tasks that -fit with the plan to implement this spec (A task to link to a patch in gerrit). - -Spec Notes ----------- - - -There are occasions when a spec is approved and the code does not land in -the cycle it was targeted for. For these cases, the workflow to get the spec -into the next release is as below: - -* Anyone can propose a patch to heat-specs which moves a spec from the - previous release backlog into the new release directory. - -The specs which are moved in this way can be fast-tracked into the next -release. Please note that it is required to re-propose the spec for the new -release and it'll be evaluated based on the resources available and cycle -priorities. - -Heat Spec Lite --------------- - -Lite specs are small feature requests tracked as StoryBoard stories, and tagged -with 'spec-lite' and 'priority-wishlist' tag. These allow for submission -and review of these feature requests before code is submitted. - -These can be used for small features that don’t warrant a detailed spec to be -proposed, evaluated, and worked on. The team evaluates these requests as it -evaluates specs. - -Once a `spec-lite` story has been approved/triaged as a -Request for Enhancement(RFE), it’ll be targeted for a release. - -The workflow for the life of a spec-lite in StoryBoard is as follows: - -* File a story with a small summary of what the requested change is and - tag it as `spec-lite` and `priority-wishlist`. -* Create tasks that fit to your plan in story. -* The story is evaluated and marked with tag as `triaged` to announce - approval or `Invalid` to request a full spec or it's not a valided task. -* The task is moved to `Progress` once the code is up and ready to - review. -* The task is moved to `Merged` once the patch lands. -* The story is moved to `Merged` once all tasks merged. - -The drivers team will discuss the following story reports in IRC meetings: - -* `heat stories `_ -* `heat story filter `_ - - -Lite spec Submission Guidelines -------------------------------- - -When a story is submitted, there is field that must be filled: ‘Description’. - -The ‘Description’ section must be a description of what you would like -to see implemented in heat. The description should provide enough details for -a knowledgeable developer to understand what is the existing problem and -what’s the proposed solution. - -Add `spec-lite` tag to the story. - - -Lite spec from existing stories -------------------------------- - -If there's an already existing story that describes a small feature suitable for -a spec-lite, add a `spec-lite` tag to the story. There is no need to create a new -story. The comments and history of the existing story are important for its review. diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000000..939bc3e8a5 --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1,47 @@ +============================ +So You Want to Contribute... +============================ +For general information on contributing to OpenStack, please check out the +`contributor guide `_ to get started. +It covers all the basics that are common to all OpenStack projects: the accounts +you need, the basics of interacting with our Gerrit review system, how we +communicate as a community, etc. +Below will cover the more project specific information you need to get started +with heat. + +Communication +~~~~~~~~~~~~~ +* IRC channel #heat at OFTC +* Mailing list (prefix subjects with ``[heat]`` for faster responses) + http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss + +Contacting the Core Team +~~~~~~~~~~~~~~~~~~~~~~~~ +Please refer the `heat Core Team +`_ contacts. + +New Feature Planning +~~~~~~~~~~~~~~~~~~~~ +heat features are tracked on `Storyboard `_. + +Task Tracking +~~~~~~~~~~~~~ +We track our tasks in `Storyboard `_. +If you're looking for some smaller, easier work item to pick up and get started +on, search for the 'low-hanging-fruit' tag. + +Reporting a Bug +~~~~~~~~~~~~~~~ +You found an issue and want to make sure we are aware of it? You can do so on +`Storyboard `_. + +Getting Your Patch Merged +~~~~~~~~~~~~~~~~~~~~~~~~~ +All changes proposed to the heat project require one or two +2 votes +from heat core reviewers before one of the core reviewers can approve +patch by giving ``Workflow +1`` vote. + +Project Team Lead Duties +~~~~~~~~~~~~~~~~~~~~~~~~ +All common PTL duties are enumerated in the `PTL guide +`_. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index ac4481fb35..f5ad159f74 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,24 +1,11 @@ Heat Contributor Guidelines =========================== -In the contributor guide, you will find documented policies for -developing with heat. This includes the processes we use for -blueprints and specs, bugs, contributor onboarding, core reviewer -memberships, and other procedural items. - -.. note:: This guideline also includes documentation for developers. - .. toctree:: :maxdepth: 3 - ../getting_started/on_devstack - blueprints - architecture - pluginguide - schedulerhints - gmr - supportstatus - rally_on_gates + contributing + .. bugs contributor-onboarding core-reviewers diff --git a/doc/source/contributor/architecture.rst b/doc/source/developing_guides/architecture.rst similarity index 100% rename from doc/source/contributor/architecture.rst rename to doc/source/developing_guides/architecture.rst diff --git a/doc/source/developing_guides/blueprints.rst b/doc/source/developing_guides/blueprints.rst new file mode 100644 index 0000000000..0ff34ebbfc --- /dev/null +++ b/doc/source/developing_guides/blueprints.rst @@ -0,0 +1,16 @@ +Blueprints and Specs +==================== + +You have to create a Story in StoryBoard `heat storyboard +`_. And create tasks that +fit with the plan to implement this spec (A task to link to a patch in gerrit). + +.. note:: heat-spacs is no longer active, there's no requirement for any + feature to summit spac on it. + +Spec from existing stories +------------------------------- + +If there's an already existing story that describes feature suitable to the +story. There is no need to create a new story. The comments and history of +the existing story are important for its review. diff --git a/doc/source/contributor/gmr.rst b/doc/source/developing_guides/gmr.rst similarity index 100% rename from doc/source/contributor/gmr.rst rename to doc/source/developing_guides/gmr.rst diff --git a/doc/source/developing_guides/index.rst b/doc/source/developing_guides/index.rst new file mode 100644 index 0000000000..42598a6fcb --- /dev/null +++ b/doc/source/developing_guides/index.rst @@ -0,0 +1,26 @@ +Heat Deloper Guidelines +======================= + +In the deloper guide, you will find documented policies for +developing with heat. This includes the processes we use for +stories (for bugs and features), contributor onboarding, core reviewer +memberships, and other procedural items. + +.. note:: This guideline also includes documentation for developers. + +.. toctree:: + :maxdepth: 3 + + ../getting_started/on_devstack + blueprints + architecture + pluginguide + schedulerhints + gmr + supportstatus + rally_on_gates +.. bugs + contributor-onboarding + core-reviewers + gate-failure-triage + code-reviews diff --git a/doc/source/contributor/pluginguide.rst b/doc/source/developing_guides/pluginguide.rst similarity index 100% rename from doc/source/contributor/pluginguide.rst rename to doc/source/developing_guides/pluginguide.rst diff --git a/doc/source/contributor/rally_on_gates.rst b/doc/source/developing_guides/rally_on_gates.rst similarity index 100% rename from doc/source/contributor/rally_on_gates.rst rename to doc/source/developing_guides/rally_on_gates.rst diff --git a/doc/source/contributor/schedulerhints.rst b/doc/source/developing_guides/schedulerhints.rst similarity index 100% rename from doc/source/contributor/schedulerhints.rst rename to doc/source/developing_guides/schedulerhints.rst diff --git a/doc/source/contributor/supportstatus.rst b/doc/source/developing_guides/supportstatus.rst similarity index 100% rename from doc/source/contributor/supportstatus.rst rename to doc/source/developing_guides/supportstatus.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 58426e4c72..79e80923ce 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -82,24 +82,31 @@ Using the Heat Service - `OpenStack Orchestration API v1 Reference`_ - :python-heatclient-doc:`Python and CLI client <>` -.. _`OpenStack Orchestration API v1 Reference`: https://docs.openstack.org/api-ref/orchestration/v1/ +.. _`OpenStack Orchestration API v1 Reference`: https://developer.openstack.org/api-ref/orchestration/v1/ Developing Heat =============== +.. toctree:: + :maxdepth: 2 + + developing_guides/index + .. toctree:: :maxdepth: 1 - contributor/index - getting_started/on_devstack - contributor/architecture - contributor/pluginguide - contributor/schedulerhints - contributor/gmr - contributor/supportstatus - contributor/rally_on_gates api/index +For Contributors +================ + +* If you are a new contributor to Heat please refer: :doc:`contributor/contributing` + + .. toctree:: + :maxdepth: 2 + + contributor/index + Indices and tables ================== diff --git a/doc/source/operating_guides/scale_deployment.rst b/doc/source/operating_guides/scale_deployment.rst index 156f591c9b..58902f88cf 100644 --- a/doc/source/operating_guides/scale_deployment.rst +++ b/doc/source/operating_guides/scale_deployment.rst @@ -48,7 +48,7 @@ Basic Architecture ------------------ The heat architecture is as defined at :doc:`heat architecture -<../contributor/architecture>` and shown in the diagram below, where we have +<../developing_guides/architecture>` and shown in the diagram below, where we have a CLI that sends HTTP requests to the REST and CFN APIs, which in turn make calls using AMQP to the heat-engine::