Skip to content

Commit

Permalink
Move community_topics_workflow to docs.ansible.com (#1028) (#1704)
Browse files Browse the repository at this point in the history 
* Move community_topics_workflow to docs.ansible.com

* Simplify

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Mario Lenz <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Mario Lenz <[email protected]>

* Improve

* Replacing Creating a topic section content

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

* Clarify

* Update docs/docsite/rst/community/steering/community_topics_workflow.rst

Co-authored-by: Don Naro <[email protected]>

---------

Co-authored-by: Mario Lenz <[email protected]>
Co-authored-by: Don Naro <[email protected]>
(cherry picked from commit 5c49902)

Co-authored-by: Andrew Klychkov <[email protected]>
  • Loading branch information
@patchback @Andersson007
patchback[bot] and Andersson007 authored Jul 18, 2024
1 parent 76ab75b commit 679760a
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 70 deletions.
2 changes: 2 additions & 0 deletions docs/docsite/rst/community/communication.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ The `Ansible Forum <https://forum.ansible.com>`_ is a single starting point and
Take a look at the `forum groups <https://forum.ansible.com/g>`_ and join ones that match your interests.
In most cases, joining a forum group automatically subscribes you to related posts.

.. _bullhorn:

The Bullhorn
------------

Expand Down
144 changes: 74 additions & 70 deletions docs/docsite/rst/community/steering/community_topics_workflow.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,121 +4,125 @@
For other changes, create a `community topic <https://forum.ansible.com/new-topic?category=project&tags=community-wg>`_ to discuss them.
(Creating a draft PR for this file and mentioning it in the community topic is also OK.)
Ansible community topics workflow
=================================
.. _community_topics_workflow:

Community topics workflow
=========================

Overview
--------

This document describes the Ansible community topics workflow (herein after ``Workflow``) to provide guidance on successful resolving topics in an asynchronous way.
This document describes the Ansible community topics workflow to provide guidance on successful resolving topics in the asynchronous way.

The Workflow is a set of actions that need to be done successively within the corresponding time frames.
The workflow is a set of actions that need to be completed in order within the corresponding time frames.

.. note::

If you have any ideas on how the Workflow can be improved, please create an issue in this repository or pull request against this document.
The following section outlines a generic scenario for a workflow.
Workflows can vary depending on a topic's complexity and other nuances; for example, when there is a mass agreement from the beginning.

Creating a topic
----------------

Any person can `create a topic <https://forum.ansible.com/new-topic?title=topic%20title&body=topic%20body&category=project&tags=community-wg>`_ tagged with ``community-wg`` under the ``Project Discussions`` category in the `Ansible Forum <https://forum.ansible.com/>`_. A :ref:`Steering Committee member<steering_members>` can tag the forum post with `community-wg-nextmtg` to put it on the meeting agenda.

Workflow
--------

.. note::

This is a rough scenario and it can vary depending on a topic's complexity and other nuances, for example, when there is a mass agreement upfront.
Any person can :ref:`create a community topic<creating_community_topic>`.

Preparation stage
^^^^^^^^^^^^^^^^^
-----------------

A Committee person checks the topic content and asks the author, or other persons, to provide additional information if needed.
* A Committee person checks the topic's content and asks the author/other persons to provide additional information as needed.

Discussion stage
^^^^^^^^^^^^^^^^

* If the topic is ready to be discussed, the Committee person:

* Adds the ``community-wg-nextmtg`` tag if it needs to be discussed in the meeting.
----------------

* Opens the discussion by adding a comment asking the Community and the Committee to take part in it.
* By default, the discussion happens asynchronously in the topic.

* No synchronous discussion is needed (there are no blockers, complications, confusion, or impasses).
* A :ref:`steering committee <steering_responsibilities>` member can tag the forum post with ``community-wg-nextmtg`` to put it on the synchronous meeting agenda.

Voting stage
^^^^^^^^^^^^

* Depending on the topic complexity, 1-2 weeks after the discussion was opened, the Committee person formulates vote options based on the prior discussion and gives participants a reasonable amount of time to propose changes to the options (no longer than a week). The person summarizes the options in a comment and also establishes a date when the vote begins if there are no objections about the options or vote date.
* In the vote date, the vote starts with a comment from a Committee person who opens the vote and establishes a date when the vote ends ($CURRENT_DATE + no longer than 21 days; Usually it should not exceed 14 days. 21 days should only be used if it is known that a lot of interested persons will likely not have time to vote in a 14 day period).
* The Committee person labels the topic with the ``active-vote`` tag.
* The Committee person adds ``[Vote ends on $YYYY-MM-DD]`` to the beginning of the topic description.
* A vote is actually two polls, one for the Steering Committee, one for everyone else. To create a vote in a topic:

* Create a new post in the topic.

* Click the ``gear`` button in the composer and select ``Build Poll``.
------------

* Click the ``gear`` in the Poll Builder for advanced mode.
The Committee person:

* Set up the options (generally this will be Single Choice but other poll types can be used).
* Formulates vote options based on the prior discussion and gives participants up to one week to propose changes to the options. This step takes place one to two weeks after the discussion was opened, depending on the complexity of the topic.
* Summarizes the options in a comment and establishes a date for the vote to begin if there are no objections to the options.
* Starts the vote on the beginning date and establishes an end date, which is $CURRENT_DATE plus:

* Title it "Steering Committee vote" and "Limit voting" to the ``Steering Committee``.
* 7 days: simple cases
* 14 days: maximum vote length
* 21 days: only used in exceptional cases such as holiday seasons when the majority of the Committee are not able to participate in the vote
* Labels the topic with the ``active-vote`` tag.
* Adds ``[Vote ends on $YYYY-MM-DD]`` to the beginning of the topic's description.

* Do not set the close date because it cannot be changed later.

* Results should be "Always Visible" unless there is some good reason for the SC votes not to be public.

* Submit the poll (the BBcode will appear in the post) and then repeat the above for the second poll.

* The title should be "Community vote".
The vote always consists of two polls: one for the Steering Committee, one for everyone else. To create a vote in a topic:

* Create a new post in the topic.
* Click the ``gear`` button in the composer and select ``Build Poll``.
* Click the ``gear`` in the ``Poll Builder`` for advanced mode.
* Set up the options (generally this will be ``Single Choice`` but other poll types can be used).
* Title it "Steering Committee vote" and ``Limit voting`` to the ``@SteeringCommittee``.
* Do NOT set the close date because this cannot be changed later.
* Results should be ``Always Visible`` unless there is a good reason for the SC votes not to be public.
* Submit the poll (the BBcode will appear in the post):
* Repeat the above steps for the second poll:

* Title should be "Community vote".
* No group limitation.

Voting result stage
^^^^^^^^^^^^^^^^^^^

* The day after the last day of the vote, the Committee person:

* Closes the polls.
-------------------

* Removes the ``active-vote`` tag.

* Add a comment that the vote ended.

* Changes the beginning of the topic's description to ``[Vote ended]``.

* Creates a summary comment declaring the vote result.

* The vote result and final decision are announced via the `Bullhorn newsletter <https://forum.ansible.com/c/news/bullhorn/17>`_.
On the vote end date, the Committee person:

* Closes the polls if the :ref:`quorum<community_topics_workflow>` is reached, otherwise prolongs the polls.
* Removes the ``active-vote`` tag.
* Adds a comment that the vote has ended.
* Changes the beginning of the topic's description to ``[Vote ended]``.
* Creates a summary comment declaring the vote result.
* Announces the vote result and the final decision in the :ref:`Bullhorn <bullhorn>`.

Implementation stage
^^^^^^^^^^^^^^^^^^^^
--------------------

* If the topic implies some actions (if it does not, just mark this as complete), the Committee person:
No further action required
~~~~~~~~~~~~~~~~~~~~~~~~~~

* Assigns the topic to the person who is responsible for performing the actions.
The Committee person:

* Add the ``being-implemented`` tag to the topic.
* Merges an associated pull request if exists.
* Adds the ``resolved`` tag.

* After the topic is implemented, the assignee:
Further actions required
~~~~~~~~~~~~~~~~~~~~~~~~

* Comments on the topic that the work is done.
The Committee person:

* Removes the ``being-implemented`` tag.
* Assigns a person responsible for performing the actions by mentioning them in a comment.
* Adds the ``being-implemented`` tag to the topic.

* Add the ``implemented`` tag.
After the actions are done, the assignee:

* If the topic implies actions related to the future Ansible Community package releases (for example, a collection exclusion), the Committee person:
* Comments on the topic that the work is done.
* Removes the ``being-implemented`` tag.
* Adds the ``implemented`` and ``resolved`` tags.

* Adds the ``scheduled-for-future-release`` tag to the topic.
Package-release related actions required
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Checks if there is a corresponding milestone in the `ansible-build-data <https://github.com/ansible-community/ansible-build-data/milestones>`_ repository. If there is no milestone, the person creates it.
If the topic implies actions related to the future Ansible community package releases (for example, a collection exclusion), the Committee person/assignee:

* Creates an issue in ansible-build-data that references the :ref:`community topic<creating_community_topic>`, and adds it to the milestone.
* Adds the ``scheduled-for-future-release`` tag to the topic.
* Checks if there is a corresponding milestone in the `ansible-build-data <https://github.com/ansible-community/ansible-build-data/milestones>`_ repository.

* If there is no milestone, the person creates it.
* Creates an issue in ``ansible-build-data`` that references the topic and adds it to the milestone.
* After it is implemented, adds the ``implemented`` and ``resolved`` tags.

Tools
-----

We have some `scripts <https://github.com/ansible-community/community-topics/tree/main/scripts>`_ that can be used to create Ansible community announcements in the Bullhorn and similar places.
There are a few `scripts <https://github.com/ansible-community/community-topics/tree/main/scripts>`_ that can be used to create Ansible community announcements on the Bullhorn and similar locations.

.. seealso::

:ref:`steering committee <steering_responsibilities>`
Ansible Community Steering Committee

0 comments on commit 679760a

Please sign in to comment.