Merge remote-tracking branch 'dvzrv/rfc_process'

.gitlab-ci.yml

+---
+
+default:
+  image: "archlinux:latest"
+
+stages:
+  - lint
+
+rstcheck:
+  stage: lint
+  before_script:
+    - pacman --noconfirm -Syu --needed make rstcheck
+  script:
+    - make lint

.gitlab/issue_templates/idea.md

+<!--
+This template should be used for proposing a new RFC idea, discussing it and
+potentially finding collaborators to work on a merge request (the eventual
+RFC).
+-->
+
+# Idea:
+<!--
+Add the title after the "Idea: "
+-->
+
+## Summary
+<!--
+Add a short summary.
+-->
+
+## Specification
+<!--
+If there is a more defined specification already, add it here.
+-->
+
+## Drawbacks
+<!--
+If there are any known drawbacks, add them here.
+-->
+
+
+<!--
+NOTE: Do not remove the below text.
+-->
+/label ~idea ~help wanted

Makefile

+DOC_FILES=$(wildcard rfcs/*.rst) $(wildcard *.rst)
+
+all:
+
+check: lint
+
+lint:
+	rstcheck --report warning $(DOC_FILES)

README.md

-# rfcs
-
-All Arch [RFC](https://en.wikipedia.org/wiki/Request_for_Comments).
\ No newline at end of file

README.rst

+===============
+Arch Linux RFCs
+===============
+
+A Request for Comment (`RFC
+<https://en.wikipedia.org/wiki/Request_for_Comments>`_) is a way for Arch Linux
+contributors to propose, design and discuss new features and changes in
+project direction in a focused environment.
+
+RFCs start as merge requests in:
+https://gitlab.archlinux.org/archlinux/rfcs/-/merge_requests
+
+Once accepted, they can be found in:
+https://gitlab.archlinux.org/archlinux/rfcs/-/tree/master/rfcs
+
+What does an RFC do?
+--------------------
+
+The RFC process is intended to bring focus and structure to discussions of
+important changes and new features in Arch Linux. It provides a space for
+sharing and collaborating on ideas and design documents, keeping community
+discussion organized and focused on the goal of reaching a decision.
+
+Visibility and inclusivity are important values for RFCs. They are advertised
+to both staff and user communication channels so everyone can participate.
+
+An RFC is only a design document, and not a single line of code needs to be
+written for the discussion to be approved, although prototyping can be a good
+idea. An approved RFC has no timeline for when it needs to be implemented.
+
+Who can file an RFC?
+--------------------
+
+Anyone can file an RFC. However, the following restriction exists for
+contributors, that are not part of the Arch Linux Developer or Trusted User
+teams:
+
+At least one Developer or Trusted User has to support the RFC and must be
+willing to work on it in a joint effort with the contributor.
+
+When should I file an RFC?
+--------------------------
+
+If you have an idea for something and are unsure if it needs an RFC, the best
+way to find out is to just ask (e.g. by `opening an issue in this repository
+<https://gitlab.archlinux.org/archlinux/rfcs/-/issues/new>`_ and filling out
+the "idea" template).
+An RFC is much more likely to succeed if it begins life as a discussion, and
+collaborators are encouraged to start off by talking to other project members
+before submitting an RFC. This can also help gauge early support for the
+feature and work out any obvious issues or design decisions.
+
+RFCs are used for proposing "substantial" changes. The meaning of "substantial"
+is subjective, but a good start would be anything that benefits from design
+discussion. Put a different way, it is recommended to file an RFC if the design
+or implementation is not immediately clear, or if there are drawbacks or
+potential consequences that require discussion first. These might be worth
+consideration for an RFC:
+
+- New features
+- Breaking changes
+- Organizational changes, including changes to the RFC process itself
+
+Proposing an RFC
+----------------
+
+Step 0: Decide if you should file an RFC
+________________________________________
+
+As an RFC author, it is best if you only have one RFC of yours open at any
+moment. This restriction is a guideline, but you are advised to be respectful
+of other contributors who would also like their RFCs to receive attention, and
+to be cognizant of the potential cost of spreading the community's attention
+thinly across a multitude of proposals.
+
+  .. note::
+
+    To view previous or current ideas, have a look at the `issues
+    <https://gitlab.archlinux.org/archlinux/rfcs/-/issues>`_.
+
+Step 1: Fork this repository
+____________________________
+
+Fork this repository if you have not already.
+
+Step 2: Write RFC
+_________________
+
+Copy **rfcs/0000-template.rst** to **rfcs/0000-<my-proposal-title>.rst** and begin
+working on the RFC.
+
+Please put a lot of thought into your writing. A great RFC explains and
+justifies its motivations and carefully considers all drawbacks and
+alternatives. Show the reader what the problems are and how the proposal
+concretely and practically addresses them.
+
+Step 3: File merge request
+__________________________
+
+Create a merge request toward https://gitlab.archlinux.org/archlinux/rfcs. The
+open merge request itself **is** the RFC. Discussion of the RFC is held in the
+comments of the merge request.
+
+  .. note::
+
+    When creating the merge request, make sure to tick the **Allow commits from
+    members who can merge to the target branch.** checkbox in the
+    **Contribution** section.
+
+After the merge request is created, the merge request number (e.g. 42) is your RFC
+number. Then do the following:
+
+1. In the branch, rename the file from **rfcs/0000-<my-proposal-title>.rst** to
+   **rfcs/0042-<my-proposal-title>.rst**. This makes all the proposals show up
+   in ascending chronological order when someone visits the `rfcs <rfcs/>`_
+   directory.
+2. In the file itself, there is a bullet point labeled **RFC MR:**. Update this
+   so that it links to the merge request. This ensures that the discussion is
+   immediately accessible from the RFC text.
+
+These are minor housekeeping steps that keep the RFC a nice, tidy, and easily
+navigable archive. If you make a mistake in this process, it is no huge issue -
+someone else can fix it for you.
+
+Step 4: Announce
+________________
+
+After the RFC is ready to go, please announce it to `arch-dev-public
+<https://lists.archlinux.org/listinfo/arch-dev-public>`_.
+
+  .. note::
+
+    If you lack the permission to send mail to the mailing list yourself, the
+    person from the Developer or Trusted User team, that is supporting your
+    RFC, will do it for you.
+
+Here is a template:
+
+.. code::
+
+  Subject: RFC: Deprecate BadFeature
+
+  A new RFC (request for comment) has been opened here:
+
+  https://gitlab.archlinux.org/archlinux/rfcs/-/merge_requests/42
+
+  Please visit the above link for discussion.
+
+  Summary: <insert the summary section from your RFC here>
+
+Discussing an RFC
+-----------------
+
+Discussion about the RFC should happen on the RFC merge request on Arch Linux's
+GitLab. If discussions happen outside the GitLab thread, it is best to link and
+summarize them in the RFC thread to make the conversations easier to track.
+
+The RFC will likely undergo numerous revisions in the discussion process.
+
+While discussing an RFC, it is everyone's responsibility to work towards
+**reaching a conclusion**. When you make a post to the RFC thread, focus on the
+contents and implications of the RFC only.
+
+Here are some guidelines:
+
+- **Think about these important questions:**
+    - Do you agree with the proposal in its current form?
+    - Are concerns and questions adequately addressed?
+    - Do you have suggestions for how the RFC can be revised or expanded,
+      especially in the Unresolved Questions section?
+- **Do not be shy:** Even if you are not an active Arch Linux contributor, or
+  if you do not feel "qualified" to discuss the topic, please feel free to
+  directly state your opinion on an RFC, especially if it affects you in some
+  way.
+- **Stay on topic:** Starting or continuing tangential or off-topic discussions
+  is disrespectful to the RFC author and is strongly discouraged. Such
+  discussions often dilute the thread and make it hard to identify what the
+  community's decision should be. The purpose of the RFC thread is to reach a
+  conclusion, and any commentary that does not contribute to that is damaging
+  to the RFC process.
+- **Civility and respect:** Like all other discussions that happen in the Arch
+  Linux community, RFC discussions are governed by our `Code of Conduct
+  <https://gitlab.archlinux.org/archlinux/service-agreements/-/blob/master/code-of-conduct.md>`_.
+  Creating an RFC is a laborious project. Commenting on an RFC should be done
+  with respect and empathy for the hard work that the author has put into it.
+- **Avoid scope creep:** You should make suggestions on how the RFC can be
+  revised or expanded, but be careful not to expand it too much and develop it
+  into something far more ambitious than was originally intended.
+
+Finalizing an RFC
+-----------------
+
+When the RFC seems ready to conclude, all staff members may make a motion for a
+Final Comment Period. The Final Comment Period lasts 14 days, and has a
+*disposition* to either **pass** or **reject**.
+
+To make a motion for a Final Comment Period, leave a comment on the merge
+request thread or use GitLab's approval functionality (for a positive
+affirmation). The Final Comment Period should also be announced on
+`arch-dev-public <https://lists.archlinux.org/listinfo/arch-dev-public>`_.
+
+Here is a template:
+
+.. code::
+
+  Subject: RFC Final Comment Period: Deprecate BadFeature
+
+  An RFC has now entered Final Comment Period. In 14 days, discussion will end
+  and the proposal will either be accepted, rejected or withdrawn:
+
+  https://gitlab.archlinux.org/archlinux/rfcs/-/merge_requests/42
+
+  Please visit the above link for discussion.
+
+  Summary: <insert the summary section from your RFC here>
+
+When should the Final Comment Period start? There does not need to be a
+consensus with everyone involved (which is usually impossible), but the RFC
+should be in a state where the author feels that the writing effort is
+complete, the arguments have been clearly articulated, discussions are resolved
+and drawbacks acknowledged in the RFC's text, and there is not a strong
+consensus *against* the proposal.
+
+Sometimes, RFCs can reach points of disagreement where no clear consensus is in
+sight. Unfortunately, there is no way that this RFC process can solve such
+issues, and these have to be handled on a case-by-case basis.
+
+If no important developments occur during this time frame, someone with write
+access merges (for passed RFCs) or closes (for rejected RFCs) the RFC PR.
+
+At any point, the RFC author can also choose to **withdraw** an RFC, with no
+14-day grace period necessary.
+
+Implementation of an RFC can start before, during, or after it has been
+approved. In fact, if you propose an RFC, you do not need to be the person to
+implement it, but usually the implementer is the same person as the RFC author.
+
+About the RFC process
+---------------------
+
+This is not a legal document, and you should not spend a lot of time analyzing
+its wording. This process is intentionally quite informal and subjective.
+Situations will come up that may not have been anticipated by this article, and
+they should be handled on a case-by-case basis.
+
+If something is ambiguous in this article, that means it is left up to
+discussion. If something is a persistent cause of confusion, then it may be
+wise to amend the RFC process itself for clarification.
+
+License
+-------
+
+All contributions are licensed by their respective authors under the terms of
+the `CC-BY-SA 4.0 License
+<https://creativecommons.org/licenses/by-sa/4.0/legalcode>`_.

rfcs/0000-template.rst

+=====
+Title
+=====
+
+- Date proposed: yyyy-mm-dd
+- RFC MR: https://gitlab.archlinux.org/archlinux/rfcs/-/merge_requests/0000
+  **update this number after RFC merge request has been filed**
+
+Summary
+-------
+
+Short description, 1-2 sentences.
+
+Motivation
+----------
+
+Introduce the topic. If this is a not-well-known section of Arch Linux, a
+detailed explanation of the background is recommended.
+
+Some example points of discussion:
+
+- What specific problems are you facing right now that you're trying to address?
+- Are there any previous discussions? Link to them and summarize them (don't
+  force your readers to read them though!).
+- Is there any precedent set by other software? If so, link to resources.
+
+Specification
+-------------
+
+A concrete, thorough explanation of what is being planned.
+
+Drawbacks
+---------
+
+Carefully consider every possible objection and issue with your proposal. This
+section should be updated as feedback comes in from discussion.
+
+Unresolved Questions
+--------------------
+
+Are there any portions of your proposal which need to be discussed with the
+community before the RFC can proceed? Be careful here -- an RFC with a lot of
+remaining questions is likely to be stalled. If your RFC is mostly unresolved
+questions and not too much substance, it may not be ready.
+
+Alternatives Considered
+-----------------------
+
+A list of alternatives, that have been considered and offer equal or similar
+features to the proposed change.

rfcs/0001-using-rfcs.rst

+==========
+Using RFCs
+==========
+
+- Date proposed: 2021-02-03
+- RFC MR: https://gitlab.archlinux.org/archlinux/rfcs/-/merge_requests/1
+
+Summary
+-------
+
+A Request for Comment (RFC) is a way for Arch Linux contributors to propose,
+design, and discuss new features and changes in project direction in a focused
+environment.
+
+Motivation
+----------
+
+Finding consensus on overarching or more involved topics in Arch Linux has
+historically been driven by discussions on mailing lists, in the distribution's
+various IRC channels, the wiki and the forums.
+While under certain circumstances this process is still valid and does work, it
+has a tendency to lead to unfocused and inconclusive discussions while lacking
+a transparent process.
+In addition, the results of decision-making are often oblique to newcomers, as
+they may only exist in the logs of chats or mailing lists, that are not
+accessible to everyone.
+When considering the different entities (project leader, developers, trusted
+users, support staff) that Arch Linux consists of, it becomes apparent that
+distribution-wide topics do not have a platform, as the specific entities have
+specialized (access-restricted) communication channels and concern themselves
+(sometimes exclusively) with a specialized topic.
+
+With the wiki article `Governance And Decision Making
+<https://wiki.archlinux.org/index.php/DeveloperWiki:Governance_And_Decision_Making>`_,
+an attempt has been made to outline the existing decision making processes and
+put them into context with one another.
+The RFC process is meant to guide and transform the distribution as a whole,
+in contrast to the various specialized entities (project leader, developers,
+trusted users, support staff) and their respective communication channels.
+
+To increase transparency, source and value the knowledge and inspiration of the
+entire community, an RFC based process can be used to achieve a more focused
+workflow for discussing overarching topics and reaching a conclusion for the
+entire distribution, while archiving discussion and consensus in a standardized
+form.
+
+Specification
+-------------
+
+The repository https://gitlab.archlinux.org/archlinux/rfcs is used to explain
+how to create, discuss, finalize and to host the accepted and rejected RFCs.
+An RFC is filed by creating a merge request toward the repository.
+
+Anyone is able to create an RFC. However, contributors outside of the Arch
+Linux Developer or Trusted User teams are only allowed to create an RFC, if at
+least one Developer or Trusted User supports the effort and helps develop it.
+
+New RFC proposals are announced on the `arch-dev-public
+<https://lists.archlinux.org/listinfo/arch-dev-public>`_ mailing list and are
+open for discussion and contribution in the merge request until finalized.
+
+Once finalized, the RFC is entering its final comment period, which is again
+announced on the `arch-dev-public
+<https://lists.archlinux.org/listinfo/arch-dev-public>`_ mailing list and lasts
+for 14 days. The final comment period is used to gather the motion of all
+participants (again as part of the merge request) to either lead to a passed
+(by merging the merge request) or rejected (by rejecting the merge request)
+RFC. Participants can either use GitLab's approval feature to approve of the
+RFC, or leave a comment for a more nuanced motion.
+
+The described process allows developers, trusted users, support staff and users
+alike to write an RFC and propose a change in direction for the distribution.
+Ideas for RFCs may be proposed and discussed by creating a new `issue
+<https://gitlab.archlinux.org/archlinux/rfcs/-/issues/new>`_ using the "idea"
+template. Existing ideas for RFCs can be found by browsing the `issues
+<https://gitlab.archlinux.org/archlinux/rfcs/-/issues>`_.
+
+Drawbacks
+---------
+
+The RFC workflow breaks with the old way of reaching consensus and might be
+perceived as bureaucratic.
+
+Unresolved Questions
+--------------------
+
+None.
+
+Alternatives Considered
+-----------------------
+
+- Mailing lists: The existing mailing list infrastructure has been used to
+  reach consensus on various topics over the years. However, finding the
+  reached consensus in a comprehensible format is not easy and depending on
+  topic can be hidden on an access restricted mailing list.
+- IRC channels: The existing staff related IRC channels on freenode.net are
+  frequently used to reach consensus on minor topics, which then usually find
+  their way into e-mails or other announcements. However, not all staff is
+  present on IRC (at all times of the day), so it is easy to miss discussions
+  or any reached consensus in this medium, if it is not propagated publicly
+  elsewhere.