openstack/governance-sigs
Code Issues Proposed changes

Reorganize SIG guidelines

Browse Source 
Reorganize and simplify SIG guidelines, so that creating and operating
a SIG does not seem so daunting. In particular:

- Remove redundant information (like the definition of a SIG) and
  generally be more concise
- Regroup SIG lifecycle guidelines (creating, updating, retiring) in
  the same chapter rather than spread it out across all the document
- Be generally less prescriptive and more on the 'best practices' side
- Mention SIG statuses as part of the SIG lifecycle guidelines, rather
  that on its own separate document
- Remove the "completed" status which is redundant with the presence in
  the completed-sigs.yaml file

Change-Id: Id1a754512f08bed55926dd7b65916c1f42fb446f
This commit is contained in:
Thierry Carrez 2020-08-21 11:53:22 +02:00
parent 77c2344824
commit 709a567071
6 changed files with 164 additions and 384 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
completed-sigs.yaml
View File

@ -12,5 +12,4 @@ Upgrade:
upgrades and online 'rolling' upgrades, by providing a forum for
cross-project collaboration between operators and developers to
document and codify best practice for upgrading OpenStack.
status: completed
url: https://wiki.openstack.org/wiki/Upgrade_SIG

1
doc/source/_extra/.htaccess Normal file
View File

@ -0,0 +1 @@
redirect 301 /reference/sig-status.html /reference/sig-guideline.html#keeping-sig-status-up-to-date

7
doc/source/_exts/sigtable.py
View File

@ -93,9 +93,10 @@ class SIGTable(Table):
entry = nodes.entry()
para = nodes.raw('', cell, format='html')
elif h.lower() == "status":
cell = ("<a href=https://governance.openstack.org/sigs/"
"reference/sig-status.html>%s</a>"
) % all_teams[team]['status']
s = all_teams[team]['status'].lower()
cell = ('<a href="https://governance.openstack.org/sigs/'
'reference/sig-guideline.html#%s">%s</a>'
) % (s, s)
entry = nodes.entry()
para = nodes.raw('', cell, format='html')
elif h.lower() == "chairs":

5
doc/source/index.rst
View File

@ -29,8 +29,3 @@ same way contributing to an OpenStack project team does.
:maxdepth: 4
reference/sig-guideline
.. toctree::
:maxdepth: 1
reference/sig-status

487
doc/source/reference/sig-guideline.rst
View File

@ -3,71 +3,96 @@ Guidelines for OpenStack SIGs (Special Interest Groups)
=======================================================
Before we dive into more details, it is important to learn what a SIG is and
what the differences are to any other group. Please check
what the differences are to other work groups in OpenStack. Please check
`Comparison of Official Group Structures`_ for more detail.
OpenStack SIGs (Special Interest Groups) are teams within the community where
we collaborate to bring unified discussions for all community members who
share a common interest. As examples, SIGs can be but are not limited to being
a first stage in the development of new projects, feature requests, standards
adoption, policy implementation, adjacent community work, and just general
discussion(s).
SIGs are governed by the `OpenStack Technical Committee`_.
Finding a SIG
=============
There are now multiple SIGs formed. check all `SIGs`_ to find if any SIG
related to you.
Creating SIG
============
The one must-do thing for forming a SIG is to register the SIG under
`SIG Governance`_. And the rest are optional, you can consider any of them if
applied.
SIGs lifecycle
==============
Before creating a SIG
---------------------
All actions here are optional, you can consider any actions if they applied.
Before creating a SIG, you should check out the existing `SIGs`_ and see if
your goals could not be shared with an existing group.
Gathering opinions
~~~~~~~~~~~~~~~~~~
If not, you should raise a thread on the openstack-discuss mailing-list about
creating a new SIG. That should allow you to raise visibility of the SIG,
get more feedback, refine the SIG scope, and recruit more volunteers.
It's always nice to get more feedback, more hands, and attention at first step.
Creating a SIG
--------------
Name of SIG
~~~~~~~~~~~
To formally propose a SIG you'll need to propose a change to the
`SIG Governance`_ file. That change will be reviewed and approved by the
`OpenStack Technical Committee`_.
Name can be a combination of ASCII letters, `-` and space.
The change should include the chosen name for the SIG (a combination of
ASCII letters, `-` and space), the proposed SIG scope, the initial status
(usually "forming") and the name of the SIG chair(s). It's strongly
encouraged to have more than one chair in order to spread the load.
.. note::
The name of a SIG can be changed after it's created, For example, a SIG
might consider changing its name when trying to target a wider range of
goals.
Particular attention should be paid to the SIG scope. Documenting down the
very reason for this SIG will help others who have similar interests to join
this group. It's important to learn why we need to form a SIG, where we need
this SIG, and what's the goal and responsibility of this SIG.
Meaning of this SIG
~~~~~~~~~~~~~~~~~~~
Here is an `example of a SIG creation request`_.
Documenting down the very reason for this SIG will help others who have similar
interests to join this group. It's important to learn why we need to form a
SIG, where we need this SIG, and what's the goal and responsibility of this
SIG. Once a SIG is created, it's alway needed to review the SIG and check what
people in the group should be doing next. And review leads to plans, plan to
lead to actions, and the accomplishment of every action will bring SIG closer
to its mission. And like the name of SIG, the mission of SIG might also change
through time. It's essential to update the information around if you plan to
change the mission or name of SIG. Make sure all members aware of the process
and result so they might be able to join the discussion.
Keeping SIG status up to date
-----------------------------
Select SIG chairs
~~~~~~~~~~~~~~~~~
Once the SIG is approved, it is important to keep its filing in
`SIG Governance`_ up to date. In particular, keeping the status, chairs,
and scope up to date.
Every SIG can appoint multiple SIG chairs, and it's encouraged to have more
than one chair so SIG can have a more flexible schedule.
A chair is encouraged as a moderator for the following works:
SIG status may be:
forming
~~~~~~~
The SIG is still setting up. This status also applied to SIG which needs to
regroup.
active
~~~~~~
The SIG reaches out for discussion, have plans for current
cycle, host meetings or send messages about status out to the mailing-list
regularly.
advisory
~~~~~~~~
The SIG is not actively meeting or driving specific goals every cycle. SIG
members stay around for help, make sure everything stays working and
provide advice when needed.
The SIG will keep the owned repository or documents up to date and will accept
updates on-demand.
unknown
~~~~~~~
SIG status is unknown, the TC is currently working to update its status.
Retiring a SIG
--------------
Inactive SIGs can be made "advisory" if SIG members are still available for
answering questions, or they can be retired.
To retire a SIG, propose a change that moves its definition from
`SIG Governance`_ to the `Completed SIGs`_ file, removing the status field.
Best practices for running a SIG
================================
SIG chairs role
---------------
A chair is encouraged as a moderator for the following work:
* Organize meeting agenda and host meetings
* Organize polling
@ -77,102 +102,38 @@ A chair is encouraged as a moderator for the following works:
task.
* Welcome new members to join the SIG.
.. note::
It might not be a specific chair's responsibility to make sure the `how
to join this SIG` guideline is completed, but chairs are encouraged to
assist new members to join the SIG. The moderator role is not
limited to chairs. Chairs can delegate to any trustworthy SIG members.
SIG communications
------------------
Set up SIG communications
-------------------------
`Set up SIG communications`_ will definitely help to have a place for all
members to join, share, and trigger discussions. Here are some general ways:
Due to SIG differences, each SIG might have its own way to communicate. The
only requirement is that the SIG communications are well documented, so that
interested parties can easily join. Here are a few suggestions:
Mailing List
~~~~~~~~~~~~
Asynchronous communication between SIG members happens on the
`OpenStack-discuss mailing-list`_, prefixing the subject with[$signame-sig]
where$signame matches the SIG’s name. SIG work output can, of course, be posted
to other mailing-lists as needed to reach other groups.
`OpenStack-discuss mailing-list`_, prefixing the subject with [$signame-sig]
where $signame matches the SIG’s name. SIG work output can, of course, be
posted to other mailing-lists as needed to reach other groups.
IRC
~~~
IRC is the preferred method of communication as it aligns with historical and
current OpenStack community best practices for simple messaging, and is also
required for TC governed projects. It is understood that for some IRC does
not come with enough features by default and programming a bot to offer
additional features is beyond some; skill or patience to create/maintain. If
a SIG does decide to use an alternative to IRC, we ask that in keeping with
the Four Opens, in particular Open Community, that you do so by ensuring
meeting logs are stored/archived.
IRC is the preferred method of communication as it aligns with OpenStack
community best practices for inclusive, synchronous messaging.
Slack
~~~~~
If your SIG uses a specific IRC channel, Opendev provides a number of IRC bots
to assist with logging. You can read more about `IRC services`_ and see an
`example for adding status/meeting bot to channel`_.
Free team accounts with Slack are not sufficient enough to meet
archiving/storage of logs alone. A great alternative is to connect
Slack with IRC and then follow the instructions for logging an IRC
channel. Check detail for `Slack+IRC connector`_. And
`docker image for Slack+IRC connector`_ is also available.
Due to SIG differences, each SIG might have its own way to communicate. It will
be nice if SIG can put detail information (like specific channel links and
guidelines for how to join) on document so anyone who plans to join the SIG
might know.
Process to create a SIG
-----------------------
This part introduces how to set up a SIG, and provides examples for reference.
.. note::
This guideline will reuse part of `project creator guideline`_ so we don't
need to rewrite everything again.
Register SIG
IRC meetings
~~~~~~~~~~~~
First and the only must-do step, register this SIG to `SIG Governance`_.
You need to sign up SIG, SIG chairs and general link for more detail
information of this SIG in openstack/governance-sig for formal approval.
Here's an `example for register a SIG`_.
.. note::
You might need to check if the information on SIG is still up to date.
.. note::
All actions after the first step are optional, you can consider any actions
if they applied.
IRC setup
~~~~~~~~~
If you're transforming from another structure (like a Working Group or Project
team) to SIG, you may keep using existing IRC channel. And if you plan to
create a new IRC channel, please reference for `IRC guideline`_.
If you're creating a new IRC channel, name rule of the channel should be
`openstack-${SIG_NAME}`. For example, the IRC channel for auto-scaling SIG
is `#openstack-auto-scaling`.
Here's an `example for adding status/meeting bot to channel`_.
.. note::
Make sure you read through IRC guidelines before you start to create a new
channel.
Meeting setup
~~~~~~~~~~~~~
You should consider to set up meeting schedule for SIG. SIG members can
decide the meeting schedule (frequency and location) and make sure there
will be moderator for each meeting. Here's an
`example for adding meeting schedule`_ to `meeting list`_. And
`example for adding meetbot to IRC channel`_.
If you run regular SIG meetings, you should consider to post the meeting
schedule for SIG. SIG members can decide the meeting schedule (frequency
and location) and make sure there will be moderator for each meeting.
Here's an `example for adding meeting schedule`_ to `meeting list`_.
.. note::
Meeting location can be at SIG's IRC channel or other public places if
@ -180,216 +141,86 @@ will be moderator for each meeting. Here's an
meeting). Make sure meeting location allows public access so everyone can
join.
Repository
~~~~~~~~~~
SIG can have its own repository, however, under any circumstances, SIG can't
release a deliverable service by itself. If a SIG needs to release any
services, it should be maintained under any specific projects instead. You can
find some detail about this in `Comparison of Official Group Structures`_.
There's also a `guideline for project repository`_ for your reference.
The most different place is you should register repository under
`sigs-repos.yaml`_ for SIG instead. You also need to
`add Gerrit permission`_ and `ask Infra team to create core team`_ for
Gerrit. Here's an `example for register a repository under SIG`_ and
`example for setup config for repository`_.
Create StoryBoard
~~~~~~~~~~~~~~~~~
It's recommended to create StoryBoard to track tasks in SIG. Adding
`use_storyboard: true` in `gerrit/projects.yaml`_ to automatically generate
a project in StoryBoard. It's allowed to track tasks for SIG in its own
way if another system seems to be a more reasonable place. But always consider
the situation when you got tasks from multiple projects to track. An
`example for add config in gerrit/projects`_ and generate
`their own storyboard`_.
Setup Zuul jobs
~~~~~~~~~~~~~~~
Setup Zuul jobs for SIG is not that much different than a project, please
reference `zuul guideline`_ for more detail.
One of most common job for SIGs is documentation test job. An example for how
you can `add your own documentation test job`_
(and a `following update for documentation job`_).
Initial document structure
~~~~~~~~~~~~~~~~~~~~~~~~~~
One of the most common functionalities of SIG is to provide documentation. Here
are a few things you can consider to document down:
* Use cases (user stories)
* what's xxx-SIG guideline: What's this SIG doing, what's the scope, goals,
and SIG mission.
* How to join this SIG
General information is always nice for a new member of SIG. Which might
include:
* Links to all resources for this SIG which may include StoryBoard,
documents, repository, Gerrit, Communication channel information (like
IRC, Slack, etc.).
* How to contribute
* Help needed list for SIG, or what's cycle goal for SIG.
* Concept guideline: Concept guideline for this special interest to
explain when we need it, which services are considered a part of this, and
what basic consideration should take place. An
`example for concept guideline`_ for auto-scaling SIG.
* Specific guidelines, or white papers
Here's an example for `how to set up the Initial Sphinx structure`_ and
`its Zuul job`_.
.. note::
For Initial documentation, it's hard to complete all documentation (to
perfect stage) at once. We need to at least provide well `How to join
this SIG` and `what's xxx-SIG guideline` so new join members always
feel welcome.
Running a SIG
=============
We generally didn't provide much limits to SIGs because each SIG might need
totally different tools, and styles to achieve their mission. Here we try to
provide some guidelines for tasks you might find fit for your SIG.
Active meeting and channel
--------------------------
To have regular meetings and have people answering on channel helps people
to find this SIG. Share new update information in the channel also help SIG
members to get a better understanding of current status for tasks in SIG.
Expose SIG
----------
Special interest group (SIG) usually needs all hands from developers,
operators, and users. And in order to get attention, valid feedbacks, good
ideas, and action takers, get more attention on tasks that SIG is focused on
is always a good option.
Summit+PTG
----------
We encourage every SIG to join Summit and PTG if that's available option. You
can consider to have:
* PTG rooms for all technical discussion needs for SIG
* Feedback Forum session for all general feedbacks from community
* Next step or cycle plan discussion. Which might be a forum or PTG discussion.
* SIG Update. which might be better fit as a Summit session or a PTG topic
(since people expect Forum to have discussions and action output from Forum,
a general SIG update might not be a well fit).
* Answering call for presentation for each Summit is also encouraged.
Here are some options for consideration:
* Hands-on workshop for use case
* General user story of this special interest
* Community track sessions to share SIG builds experiences.
Template
--------
Provide and consistently update templates. SIG can consider generating
templates based on its interest (like feature request, bug report, use case
sharing, etc), so contributors don't need to rewrite everything on their own.
An `example for self-healing SIG provides a use case template`_.
Manage StoryBoard
-----------------
If SIG uses StoryBoard for tracking cross-project tasks or SIG tasks. Like
maintaining a project, SIG tasks should be consistently updated. Also,
(ideally) every SIG action should have its own tasks in StoryBoard so it will
be easier to track actions. SIG can also consider providing its own StoryBoard
for users to provide related bug reports or feature requests. This is useful
because we can have a single point to discuss, and create subtasks to track bug
fixes or feature implementation cross-project.
Gate jobs
---------
If SIG generates Zuul jobs by its own (like a cross-project gate job) or use
exists one (like documentation gate job), it's important to make sure the gate
job is up to date and stays green (unbroken). Also if you building a
cross-project job, consistently check the health and performance of that job is
important because cross-project functionality usually more complex to use.
And you don't want to slow down any projects because of the high failure rate
of a specific cross-project gate job. For example, it's possible to consider
building a cross-project gate job for self-healing use cases uses Mistral,
Vitrage, and Monasca. That means this job might be adopted in Mistral, Vitrage,
and Monasca. Any increase failure rate of that job will reflect upon all three
projects.
Health check
------------
It's encouraged to consistently provide health check of a SIG to make sure
everything is on track, good progress for each SIG task, and all current
resources are up to date. It's always friendly to announce chances (like
chances of meeting schedule, or documentation link) through any SIG channels.
Health check results can be sent out through ML so others might get more
up-to-date information.
Tag your SIG
------------
SIG can be tagged with different status and let people understand the SIG's
purpose and current state.
You can find all available status tag under
:doc:`SIG status </reference/sig-status>`.
SIG newsletter
--------------
Post SIG news regularly
~~~~~~~~~~~~~~~~~~~~~~~
It's encouraged to provide updates for all who might be interested in
learning. Through a mailing list, instant messaging channels, or anywhere
you think that helps. The reasons for doing so are both to attract new
members to join, and to make sure others know about the new changes. For
example, once your SIG creates nice documents that you believe will help
others, you can send a mailing list for it, and also mention it in IRC/Slack.
learning. This can be done through the mailing list, or instant messaging
channels. Keeping everyone informed of the SIG progress helps to attract new
members, and to make sure others know about the new changes.
Attend events
~~~~~~~~~~~~~
We encourage every SIG to participate to the Summit and PTG events if possible.
SIGs can have:
* PTG rooms for SIG in-person group discussions
* Forum sessions to get wider community feedback on issues within the SIG
scope.
* Speaking slots are reserved for SIG update presentations at Summits. This
is a great way to spread the word about a SIG and recruit new members.
SIG resources
-------------
Git repositories
~~~~~~~~~~~~~~~~
While SIGs do not produce software that is included in the regular OpenStack
release, SIGs can own git repositories, for example for documentation or add-on
software.
You can read more about `how to create a new git repository`_. In particular,
you will need to register this new repository in the `sigs-repos.yaml`_ file
(like in this `example for register a repository under SIG`_),
`add Gerrit permission`_ and `ask Infra team to create core team`_ for
Gerrit.
Doc repository
~~~~~~~~~~~~~~
A classic use case for a git repository in a SIG is to publish peer-reviewed
documentation. Using `Sphinx`_ and `Zuul jobs`_ it is easy to publish
documentation under `docs.openstack.org`_.
A good example of such a repository is `openstack/auto-scaling-sig`, which
includes `Sphinx`_ configuration and `Zuul jobs`_ to publish the
`Auto-scaling SIG docs`_.
StoryBoard task tracker
~~~~~~~~~~~~~~~~~~~~~~~
If you use a git repository, you can use `StoryBoard`_ to track tasks in the
SIG. Adding `use_storyboard: true` to the repository definition in
`gerrit/projects.yaml`_ will automatically generate a corresponding project
in StoryBoard. Here is an `example for add config in gerrit/projects`_.
.. _Comparison of Official Group Structures: https://governance.openstack.org/tc/reference/comparison-of-official-group-structures.html
.. _OpenStack Technical Committee: https://governance.openstack.org/tc/
.. _SIGs: https://governance.openstack.org/sigs/
.. _SIG Governance: https://opendev.org/openstack/governance-sigs/src/branch/master/sigs.yaml
.. _Set up SIG communications: https://governance.openstack.org/sigs/#sig-communications
.. _OpenStack Technical Committee: https://governance.openstack.org/tc/
.. _example of a SIG creation request: https://review.opendev.org/#/c/632252/
.. _OpenStack-discuss mailing-list: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
.. _project creator guideline: https://docs.openstack.org/infra/manual/creators.html
.. _example for register a SIG: https://review.opendev.org/#/c/632252/
.. _IRC guideline: https://docs.openstack.org/infra/system-config/irc.html
.. _Completed SIGs: https://opendev.org/openstack/governance-sigs/src/branch/master/completed-sigs.yaml
.. _IRC services: https://docs.openstack.org/infra/system-config/irc.html
.. _example for adding status/meeting bot to channel: https://review.opendev.org/#/c/656796
.. _example for adding meeting schedule: https://review.opendev.org/#/c/656810/
.. _meeting list: http://eavesdrop.openstack.org/
.. _example for adding meetbot to IRC channel: https://review.opendev.org/#/c/656796/1/hiera/common.yaml
.. _guideline for project repository: https://docs.openstack.org/infra/manual/creators.html#add-new-repository-to-the-governance-repository
.. _how to create a new git repository: https://docs.openstack.org/infra/manual/creators.html
.. _sigs-repos.yaml: https://opendev.org/openstack/governance/src/branch/master/reference/sigs-repos.yaml
.. _example for register a repository under SIG: https://review.opendev.org/#/c/637126
.. _example for setup config for repository: https://review.opendev.org/#/c/637125/
.. _add Gerrit permission: https://docs.openstack.org/infra/manual/creators.html#add-gerrit-permissions
.. _ask Infra team to create core team: https://docs.openstack.org/infra/manual/creators.html#update-the-gerrit-group-members
.. _Sphinx: https://www.sphinx-doc.org/
.. _Zuul jobs: https://zuul-ci.org/docs/zuul/index.html
.. _docs.openstack.org: https://docs.openstack.org/
.. _openstack/auto-scaling-sig: https://opendev.org/openstack/auto-scaling-sig/
.. _Auto-scaling SIG docs: https://docs.openstack.org/auto-scaling-sig/
.. _StoryBoard: https://storyboard.openstack.org/
.. _gerrit/projects.yaml: https://github.com/openstack/project-config/blob/master/gerrit/projects.yaml
.. _example for add config in gerrit/projects: https://review.opendev.org/#/c/637125/7/gerrit/projects.yaml
.. _their own storyboard: https://storyboard.openstack.org/#!/project/openstack/auto-scaling-sig
.. _zuul guideline: https://docs.openstack.org/infra/manual/creators.html#add-project-to-zuul
.. _example for concept guideline: https://docs.openstack.org/auto-scaling-sig/latest/theory-of-auto-scaling.html
.. _how to set up the Initial Sphinx structure: https://review.opendev.org/#/c/656423/
.. _its Zuul job: https://review.opendev.org/#/c/659955
.. _example for self-healing SIG provides a use case template: https://opendev.org/openstack/self-healing-sig/src/branch/master/use-cases/template.rst
.. _Slack+IRC connector: https://github.com/ekmartin/slack-irc
.. _docker image for Slack+IRC connector: https://github.com/mrhillsman/dockerize-slack-irc.
.. _add your own documentation test job: https://review.opendev.org/#/c/656423/
.. _following update for documentation job: https://review.opendev.org/#/c/659955/

47
doc/source/reference/sig-status.rst
View File

@ -1,47 +0,0 @@
==========
SIG status
==========
SIGs can be tagged with different status and let people understand the SIG's
purpose and current state. You can find current status of each SIG under
`SIG Governance`_. Here are valid statuses:
active
-------
The SIG reaches out for discussion, have plans for current
cycle, host meetings or send messages about status out to the mailing-list
regularly.
forming
-------
The SIG is still setting up. This status also applied to SIG which needs to
regroup.
advisory
--------
The SIG is not actively meeting or driving specific goals every cycle. SIG
members stay around for help, make sure everything stays working and
provide advice when needed.
The SIG will keep the owned repository or documents up to date and will accept
updates on-demand.
complete
--------
The SIG completed its mission and moved to `Completed SIGs`_.
Completed SIGs can own repositories if required. But those should be marked as
unmaintained.
backlog
-------
The SIG didn't complete its mission and moved to backlog-sigs since this SIG
can't maintain itself and can't find anyone to run the chair. Backlog SIGs can
own repositories if required. But those should be mark as unmaintained.
.. _SIG Governance: https://opendev.org/openstack/governance-sigs/src/branch/master/sigs.yaml
.. _Completed SIGs: https://opendev.org/openstack/governance-sigs/src/branch/master/completed-sigs.yaml