jj/docs/governance/temporary-voting.md

# Getting Community Buy-in for Working Group Proposals

## Introduction

We're introducing a temporary process to describe how we'll gain approval to
adopt permanent governance policies - basically, how we make social and
technical decisions as a community. This temporary process describes how the
governance working group can propose these policies and how community members
can influence them and vote on them. Once permanent governance policies are in
place, the temporary process will stop being used, and the permanent governance
policies will be used instead.

## Context

The governance working group was appointed by recommendation from Martin (jj's
original author and current sole maintainer), without recommendation or approval
from the broader jj community. This isn't a problem in itself - but it does
mean that the governance working group (Austin Seipp/aseipp, Waleed
Khan/arxanas, Martin von Zweigbergk/martinvonz, and Emily Shaffer/nasamuffin)
needs to get some community approval before setting policy for the entire jj
project. If we skip this step, we risk being perceived as exercising excessive
control over the project.

## Goals and Non-Goals

* This process will be used to approve things like a `governance.md` (describing
  the formal structure of governance used for this project), technical design
  approval process, and code review process.
* This is **not** a process that will be used forever. It is intended as a
  temporary process, only used to approve more permanent processes and policies
  for the project.
* This process is used to gather feedback, approval, and acceptance from
  invested jj community members. Current members of the community should be able
  to participate in voting without hardship.
  * Current community members include code committers, code reviewers, those
    providing user support, those providing quality, actionable feedback, those
    providing documentation (first-party or third-party), developers of
    jj-compatible tools and add-ons (like GUIs or IDE extensions), and those
    providing design input and feedback.
    * If you feel that you are a member of the community but do not fit into one
      of these buckets, please reach out to one of the members of the working
      group to have this list expanded.
* This process **is** the primary way for general community members to influence
  governance policies and processes. It should invite constructive feedback and
  help us form policies that are acceptable to the jj group as a whole.
  * It's intended to meet community members where they are - on GitHub and on
    Discord, where all development occurs and most support and technical
    discussion occurs.
* This is **not** a process for gaining unanimous agreement - there are too
  many of us for that to be feasible. Instead, it is a process for gaining
  widespread community approval.

## Process

### Stage 1: Advance Notice of Effort

The working group lets the community know about upcoming policy drafts they're
intending to share for approval. This must happen at least a week before
entering stage 3, and ideally should happen even earlier.

At this time, the working group should:

* Describe why the working group feels this policy is needed
* Describe the basic goals the policy should achieve
* Describe implementation details that are being considered, if any
* Create discussion thread on GitHub (and link to it from Discord). The GitHub
  discussion thread is the canonical thread for discussion and will be reused
  through the lifetime of a proposal as it moves through this process.

At this time, the community is invited to:

* Recommend additional goals, or discuss nuances of the stated goals the working
  group has already shared
* Recommend implementation details

The working group will consider these recommendations in good faith, but may
choose not to adopt them.

### Stage 2: Proposal Review Period

This stage lasts until the working group feels major concerns have been
addressed and the proposal is ready for a vote. However, **at least 72 hours**
must elapse between the proposal being published and the vote starting, to allow
community members around the globe to read and comment. Typically, this stage
should last at least one week.

At this time, the working group should:

* Share the full text of the proposal as a GitHub pull request (PR)
* Link this GitHub PR to the existing Discord notification thread and GitHub
  discussion
* Explain how the proposal meets the goals stated in Stage 1, either within the
  proposal itself or in commentary next to the proposal

At this time, the community is invited to:

* Share constructive recommendations in GitHub to modify the text of the
  proposal, or discuss nuances of the proposal's wording
* Share showstopper concerns in GitHub about the proposal, including details
  about how and why the concern is especially dire

Think of this like a code review; the goal of this stage is to build a proposal
that is representative of the community's will. Keep recommendations actionable
and constructive: "This clause discourages X; if we phrase it like "foo bar baz"
it could be less exclusive" is much more productive than "It's obvious that the
governance working group doesn't want X!"

At the discretion of the working group, but based on the outcome of the
discussion, the proposal will go to a vote **or** the proposal will be dropped.

### Stage 3: Proposal Voting Period

When the working group feels that major concerns have been addressed and is
happy with the text of the proposal, the working group will open voting on the
proposal.

* Voting occurs on GitHub using the poll feature and is advertised heavily on
  Discord during the voting period.
  * If community members want to vote but aren't able to use GitHub, they can
    message nasamuffin@ (on Discord, or nasamuffin at google dot com) with their
    vote to have it manually included. Only one working group member is listed
    in order to avoid accidental double-counting.
  * When voting against, community members should comment on the post explaining
    why and describe what change would be required for them to abstain or vote
    in favor.
  * Generally, assume that the votes may be publicly visible or may be made
    publicly visible at a later time.
* Voting is open for at least 1 week, but may be open as long as 2 weeks when
  appropriate. After that deadline, the GitHub poll will be locked.
    * The deadline must be announced at the beginning of the voting period -
      once voting has begun, the deadline cannot change.
    * The working group may set the voting period longer to encompass two
      weekends (for more participation around day jobs), for less urgent or more
      complex proposals, or to account for holidays during the voting period.
* Participants can vote in favor or against.
  * "Participants" means the group of community members as enumerated at the
    beginning of this document.

**Proposals with 2/3 or more votes in favor at the end of the voting period will
be approved.**

After voting has concluded, either:

* The proposal will be implemented (if accepted)
* The proposal may be revised and begin again at stage 2 (if rejected)
* The proposal may be abandoned (if rejected)

Deciding whether to revise or abandon is up to the discretion of the governance
working group. The working group is expected to double-check their assumption
that the goals the proposal is attempting to meet are desirable after the
proposal fails to be accepted.

### Stage 4: Implementation

Typically, implementation will look like merging the document with the policy
into the jj codebase and remembering to use that policy in conversations moving
forward.

In some cases, implementation may also involve nomination of individuals to a
group or committee. When this is necessary, expect the policy being proposed to
describe how these individuals will be nominated, both initially and moving into
the future.

It's possible (but unlikely) that during implementation, some obstacle will
arise that means the policy doesn't actually work. If this does happen, expect
the working group to be transparent with the community about the situation. We
may reuse some of all of this process to figure out how to move forward.