diff --git a/doc/source/goals b/doc/source/goals new file mode 120000 index 000000000..ac18ec985 --- /dev/null +++ b/doc/source/goals @@ -0,0 +1 @@ +../../goals \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index 53dd077eb..2b11ec426 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -28,6 +28,7 @@ Reference documents and Resolutions :titlesonly: reference/index + goals/index resolutions/index resolutions/superseded/index diff --git a/goals/index.rst b/goals/index.rst new file mode 100644 index 000000000..cc5515b37 --- /dev/null +++ b/goals/index.rst @@ -0,0 +1,113 @@ +.. _release-cycle-goals: + +====================== + OpenStack-wide Goals +====================== + +The pages in this part of the governance documentation describe +OpenStack-wide goals for each release series. + +We use these OpenStack-wide goals to achieve visible common changes, +push for basic levels of consistency and user experience, and +efficiently repay the most obvious technical debt -- across all +OpenStack projects. From a contributor perspective, they help bring +together the whole community behind some shared goals. We know this +work is worthwhile, because these goals are how we achive the +OpenStack mission together. We will build these goals based on our +shared values. + +We know this process is working when + +* Users and operators see OpenStack working well as a platform, rather + than a collection of loosely related different projects. +* We make progress on solving long-standing issues that would + otherwise have lingered indefinitely at different stages of + implementation in various projects. +* All contributors and projects know they are valued members of the + successful and thriving OpenStack community. +* Marketing communication around release time is facilitated due to + successful completion of community-wide goals during the cycle. + +Process Details +=============== + +Identifying Goals +----------------- + +The goal process enables the community of OpenStack projects to +surface common concerns and work out specific technical strategies for +addressing these concerns. This community input will enable the TC to +select specific community-wide goals for all projects to achieve +during a development cycle. We need to consider the timing, cycle +length, priority, and feasibility of the goals selected. + +We will brainstorm goals before and at each summit, using feedback +received from deployers, users, contributors, and PTLs. Those goals +will be discussed on the mailing list to collect feedback about +whether each goal is achievable and described completely. The TC will +use that input to come to consensus and make the final decisions for +OpenStack-wide goals for each cycle in time to allow planning and +other discussion at the PTG event at the start of the cycle. + +Defining Goals +-------------- + +Goals are defined here in the governance documentation to ensure that +we establish a common understanding of the expectations being set. +Goal definitions should use the provided template so they are all +formatted consistently. The goal definition does not take the place +of any blueprints, spec documents, or other planning tools used within +a project to track its work, but can be referenced from those +documents. + +To define goals for a release cycle, a TC member should set up the +series directory in one patch, and then in follow-up patches TC +members can propose specific goals. This separates the discussion for +each goal onto its own review. + +The actual goals shouldn't be completely new proposals (things no one +else in the community has seen before) because there will have been +discussion in the course of reaching consensus. + +Team Acknowledgment of Goals +---------------------------- + +After a goal is approved, each PTL is responsible for adding their +planning artifact links to the goal document before the first +milestone deadline. The planning artifact is likely to be a link to a +spec or bug, and the completion artifact is likely to be a link to one +or more committed patches. + +This step is also the indication that a project team is signing up as +agreeing to the goal and committing to do the work to complete the +goal, within their project. That commitment may mean doing it +themselves or may mean simply prioritizing reviews submitted by +others. Either way, the commitment is to have the goal completed, and +all teams are expected to commit the necessary resources to ensure +that it is finished. + +All project teams are expected to prioritize these goals above other +work. + +If the goal does not apply to a project or the project has already met +the goal, the PTL should explain why that is the case, instead of +linking to planning artifacts. + +Completing Goals +---------------- + +After a goal is completed, each PTL is responsible for ensuring that +their completion artifacts are added to the goal document before the +final release date for the cycle. + +If a goal is not completed, that information should be added, along +with any references needed to track when that work will be completed. + +Release Cycles +============== + +.. toctree:: + :glob: + :maxdepth: 2 + + */index diff --git a/goals/ocata/index.rst b/goals/ocata/index.rst new file mode 100644 index 000000000..d7d150765 --- /dev/null +++ b/goals/ocata/index.rst @@ -0,0 +1,9 @@ +======= + Ocata +======= + +.. toctree:: + :glob: + :maxdepth: 1 + + * diff --git a/goals/template.txt b/goals/template.txt new file mode 100644 index 000000000..38ebd45bc --- /dev/null +++ b/goals/template.txt @@ -0,0 +1,38 @@ +.. -*- mode: rst -*- + +================================== + (one line goal description here) +================================== + +Explain what the goal is in general terms. Include the reasoning and +justification for applying the goal to all OpenStack projects. + +Gerrit Topic +============ + +To facilitate tracking, commits related to this goal should use the +gerrit topic:: + + + +Completion Criteria +=================== + +Enumerate the items that must be true in order to call the goal +"completed" for a given project. + +#. one +#. two + +References +========== + +Provide reference links to previous discussions on the mailing list or +IRC, etherpads, wiki pages, other forms of notes, and documentation +that would be useful to a project team in working on the goal. + +Project Teams +============= + +.. Use tools/build_team_section_for_goal.py to generate the rest of + the template and paste it into this section. diff --git a/reference/new-projects-requirements.rst b/reference/new-projects-requirements.rst index 323f6222c..67886f989 100644 --- a/reference/new-projects-requirements.rst +++ b/reference/new-projects-requirements.rst @@ -61,6 +61,11 @@ When considering new projects for addition, the TC will check that: * The project should have an active team of one or more contributors +* The project participates in any goals specified by the TC, as + defined by :ref:`release-cycle-goals`. Any existing goals that are + not met should be prioritized and completed within the first year of + a team joining. + * The project meets any policies that the TC requires all projects to meet. For instance, the :doc:`project-testing-interface` diff --git a/tools/build_team_section_for_goal.py b/tools/build_team_section_for_goal.py new file mode 100755 index 000000000..3f6a7653b --- /dev/null +++ b/tools/build_team_section_for_goal.py @@ -0,0 +1,48 @@ +#!/usr/bin/env python +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +from __future__ import print_function + +import argparse +import os.path + +import yaml + +_section = ''' +Planning Artifacts: + +Completion Artifacts: +''' + + +def main(): + parser = argparse.ArgumentParser( + 'build the "Project Teams" section of a goal document', + ) + args = parser.parse_args() + + print('Paste this output to the end of the goals file:\n') + + filename = os.path.abspath('reference/projects.yaml') + with open(filename, 'r') as f: + projects = [k for k in yaml.safe_load(f.read())] + projects.sort() + + for p in projects: + print(p) + print('-' * len(p)) + print(_section) + + +if __name__ == '__main__': + main()