Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move community_topics_workflow to docs.ansible.com #1028

Merged
merged 21 commits into from
Jul 18, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
c78c575
Move community_topics_workflow to docs.ansible.com
Andersson007 Jan 11, 2024
21fa7e7
Simplify
Andersson007 Jul 12, 2024
eecf5bc
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
7f56d71
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
9d0276a
Improve
Andersson007 Jul 16, 2024
8b75621
Replacing Creating a topic section content
Andersson007 Jul 16, 2024
53801b7
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
c0d6a05
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
d78ceb1
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
b87a1e4
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
881d084
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
ab0c8d8
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
63ccc65
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
0f755bf
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
0ddf5fa
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
aa33a16
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
662b5c7
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
bf559e6
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
2af1d5f
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 16, 2024
572dae1
Clarify
Andersson007 Jul 16, 2024
596306e
Update docs/docsite/rst/community/steering/community_topics_workflow.rst
Andersson007 Jul 17, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/docsite/rst/community/communication.rst
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
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