describe a process for managing community-wide goals

One of the outcomes of the discussion at the leadership training session
earlier this year was the idea that the TC should set some
community-wide goals for accomplishing specific technical tasks to get
the projects synced up and moving in the same direction.

This patch includes the proposed process for managing those goals, a
template for describing a goal, the placeholder for goals for the Ocata
cycle, and a tool for mechanically generating part of the documents.

I had help with reviews and drafts of some portions of this text from a
bunch of other folks including jroll, dtroyer, johnthetubaguy, spamaps,
mordred, ttx, notmorgan, thingee, and amrith.

Change-Id: I46cc66eafe9dbcfda94fb6a1a8c66c2ca77de45a
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

doc/source/goals

@@ -0,0 +1 @@
+../../goals

doc/source/index.rst

@@ -28,6 +28,7 @@ Reference documents and Resolutions
    :titlesonly:
 
    reference/index
+   goals/index
    resolutions/index
    resolutions/superseded/index
 

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

goals/ocata/index.rst

@@ -0,0 +1,9 @@
+=======
+ Ocata
+=======
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   *

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::
+
+  <insert topic here>
+
+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.

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`
 

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()