Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
125 lines (61 loc) · 6.55 KB

CONTRIBUTING.md

File metadata and controls

125 lines (61 loc) · 6.55 KB

Contribution Guidelines

Pull requests are always welcome

We're trying very hard to keep our systems simple, lean and focused. We don't want them to be everything for everybody. This means that we might decide against incorporating a new request.

Create issues...

Any significant change should be documented as a GitHub issue before anybody starts working on it.

...but check for existing issues first!

Please take a moment to check that an issue doesn't already exist documenting your request. If it does, it never hurts to add a quick "+1" or "I need this too". This will help prioritize the most common requests.

Process

Clone the repository and make changes on a branch:

  1. Create the right type of issue (defect, enhancement, task, etc).
  2. Before committing, run bin/make-csvs.sh locally and commit the resultant CSVs.
  3. Name the branch N-something where N is the number of the issue.
  4. Push the branch to the remote repository and create a PR, @agora-council will automatically be added as reviewers.

Work hard to ensure your pull request is valid.

Pull request descriptions should be as clear as possible and include a reference to all the issues that they address. In GitHub, you can reference an issue by adding a line to your commit description that follows the format:

Fixes #N

where N is the issue number.

A note about the radar links: if you want to view changes to the radar but have pushed a PR to a non-master branch, simply edit the radar url to use your-branch-name instead of master. Be warned that the raw csv gets cached by Github for an indeterminate amount of time, so don't push new commits and expect to immediately see changes.

Merge approval

@agora-council use LGTM (Looks Good To Me) in comments on the code review to indicate acceptance.

A change requires LGTMs from an absolute majority of the CODEOWNERS. The Benevolent dictator for life reserves sole veto power. We recommend also getting a LGTM from the BDFL in advance of merging to avoid the possibility of a revert.

Only the Agora Council has master merge rights.

Small patch exception

There are exceptions to the merge approval process. Currently these are:

  • Your patch fixes spelling or grammar errors.
  • Your patch fixes Markdown formatting or syntax errors in any .md files in this repository

How can I become a Councilmember?

Make important contributions.

Don't forget: being a Councilmember is a time investment. Make sure you will have time to make yourself available. You don't have to be a code owner to make a difference on the project!

What is a Councilmember's responsibility?

It is every Councilmember's responsibility to:

  1. Deliver prompt feedback and decisions on pull requests.
  2. Be available to anyone with questions, bug reports, criticism etc. on their component. This includes Slack and GitHub requests
  3. Make sure their component respects the philosophy, design and road map of the project.

How are decisions made?

Short answer: with pull requests to this repository

All decisions, big and small, follow the same 3 steps:

  1. Open a pull request. Anyone can do this.

  2. Discuss the pull request. Anyone can do this.

  3. Accept (LGTM) or refuse a pull request. The relevant code owners do this (see below "Who decides what?")

    1. Accepting pull requests

      1. If the pull request appears to be ready to merge, give it a LGTM, which stands for "Looks Good To Me".

      2. If the pull request has some small problems that need to be changed, make a comment adressing the issues.

      3. If the changes needed to a PR are small, you can add a "LGTM once the following comments are adressed..." this will reduce needless back and forth.

      4. If the PR only needs a few changes before being merged, any Councilmember can make a replacement PR that incorporates the existing commits and fixes the problems before a fast track merge.

    2. Closing pull requests

      1. If a PR appears to be abandoned, after having attempted to contact the original contributor, then a replacement PR may be made. Once the replacement PR is made, any contributor may close the original one.

      2. If you are not sure if the pull request implements a good feature or you do not understand the purpose of the PR, ask the contributor to provide more documentation. If the contributor is not able to adequately explain the purpose of the PR, the PR may be closed by any Councilmember.

      3. If a Councilmember feels that the pull request is sufficiently architecturally flawed, or if the pull request needs significantly more design discussion before being considered, the Councilmember should close the pull request with a short explanation of what discussion still needs to be had. It is important not to leave such pull requests open, as this will waste both the Councilmember's time and the contributor's time. It is not good to string a contributor on for weeks or months, having them make many changes to a PR that will eventually be rejected.

Who decides what?

All decisions are pull requests, and the relevant Councilmembers make decisions by accepting or refusing pull requests. Review and acceptance by anyone is denoted by adding a comment in the pull request: LGTM. However, only currently listed CODEOWNERS are counted towards the required majority.

This repository also follows the timeless, highly efficient and totally unfair system known as Benevolent dictator for life. This means that all decisions are made in the end, by default, by <BDFL>. In practice decisions are spread across the Councilmembers with the goal of consensus prior to all merges.

The current BDFL is included in the @agora-bdfl Github group.

I'm a Councilmember, should I make pull requests too?

Yes. Nobody should ever push to master directly. All changes should be made through a pull request.

Who assigns Councilmember?

CODEOWNERS are changed via pull requests and the standard approval process - i.e. create an issue and make a pull request with the changes to the CODEOWNERS file and get a majority of LGTM from existing Councilmembers. In parallel, the @agora-council group should be kept updated with CODEOWNERS because it controls merge permissions (among other things).

How is this process changed?

Just like everything else: by making a pull request :)