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>
This commit is contained in:
Doug Hellmann 2016-07-29 16:04:38 -04:00
parent d012f5e80d
commit 5118d12464
7 changed files with 215 additions and 0 deletions

1
doc/source/goals Symbolic link
View File

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

View File

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

113
goals/index.rst Normal file
View File

@ -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

9
goals/ocata/index.rst Normal file
View File

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

38
goals/template.txt Normal file
View File

@ -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.

View File

@ -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`

View File

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