We are always thrilled to receive pull requests, and do our best to

process them as fast as possible. Not sure if that typo is worth a pull

request? Do it! We will appreciate it.

If your pull request is not accepted on the first try, don't be

discouraged! If there's a problem with the implementation, hopefully you

received feedback on what to improve.

We're trying very hard to keep the project lean and focused. We don't want it

to do everything for everybody. This means that we might decide against

incorporating a new feature.

Fork the repo and make changes on your fork in a feature branch:

- If it's a bugfix branch, name it XXX-something where XXX is the number of the

issue

- If it's a feature branch, create an enhancement issue to announce your

intentions, and name it XXX-something where XXX is the number of the issue.

Submit unit tests for your changes. Go has a great test framework built in; use

it! Take a look at existing tests for inspiration. Run the full test suite on

your branch before submitting a pull request.

Update the documentation when creating or modifying features. Test

your documentation changes for clarity, concision, and correctness, as

well as a clean documentation build. See ``docs/README.md`` for more

information on building the docs and how docs get released.

Write clean code. Universally formatted code promotes ease of writing, reading,

and maintenance. Always run `gofmt -s -w file.go` on each changed file before

committing your changes. Most editors have plugins that do this automatically.

Pull requests descriptions should be as clear as possible and include a

reference to all the issues that they address.

Pull requests must not contain commits from other users or branches.

Commit messages must start with a capitalized and short summary (max. 50

chars) written in the imperative, followed by an optional, more detailed

explanatory text which is separated from the summary by an empty line.

Code review comments may be added to your pull request. Discuss, then make the

suggested modifications and push additional commits to your feature branch. Be

sure to post a comment after pushing. The new commits will show up in the pull

request automatically, but the reviewers will not be notified unless you

comment.

Before the pull request is merged, make sure that you squash your commits into

logical units of work using `git rebase -i` and `git push -f`. After every

commit the test suite should be passing. Include documentation changes in the

same commit so that a revert would remove all traces of the feature or fix.

Commits that fix or close an issue should include a reference like `Closes #XXX`

or `Fixes #XXX`, which will automatically close the issue when merged.

The sign-off is a simple line at the end of the explanation for the

patch, which certifies that you wrote it or otherwise have the right to

pass it on as an open-source patch. The rules are pretty simple: if you

can certify the below (from

[developercertificate.org](http://developercertificate.org/)):

then you just add a line to every git commit message:

Signed-off-by: Joe Smith <[email protected]>

using your real name (sorry, no pseudonyms or anonymous contributions.)

You can add the sign off when creating the git commit via `git commit -s`.

Dear maintainer. Thank you for investing the time and energy to help

make this project as useful as possible. Maintaining a project is difficult,

sometimes unrewarding work. Sure, you will get to contribute cool

features to the project. But most of your time will be spent reviewing,

cleaning up, documenting, answering questions, justifying design

decisions - while everyone has all the fun! But remember - the quality

of the maintainers work is what distinguishes the good projects from the

great. So please be proud of your work, even the unglamourous parts,

and encourage a culture of appreciation and respect for *every* aspect

of improving the project - not just the hot new features.

This document is a manual for maintainers old and new. It explains what

is expected of maintainers, how they should work, and what tools are

available to them.

This is a living document - if you see something out of date or missing,

speak up!

It is every maintainer's responsibility to:

* 1) Expose a clear roadmap for improving their component.

* 2) Deliver prompt feedback and decisions on pull requests.

* 3) Be available to anyone with questions, bug reports, criticism etc.

on their component. This includes IRC and GitHub issues and pull requests.

* 4) Make sure their component respects the philosophy, design and

roadmap of the project.

Short answer: with pull requests to the project repository.

This project is an open-source project with an open design philosophy. This

means that the repository is the source of truth for EVERY aspect of the

project, including its philosophy, design, roadmap and APIs. *If it's

part of the project, it's in the repo. It's in the repo, it's part of

the project.*

As a result, all decisions can be expressed as changes to the

repository. An implementation change is a change to the source code. An

API change is a change to the API specification. A philosophy change is

a change to the philosophy manifesto. And so on.

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

* Step 1: Open a pull request. Anyone can do this.

* Step 2: Discuss the pull request. Anyone can do this.

* Step 3: Accept (`LGTM`) or refuse a pull request. The relevant maintainers do

this (see below "Who decides what?")

Yes. Nobody should ever push to master directly. All changes should be

made through a pull request.

All decisions are pull requests, and the relevant maintainers make

decisions by accepting or refusing the pull request. Review and acceptance

by anyone is denoted by adding a comment in the pull request: `LGTM`.

However, only currently listed `MAINTAINERS` are counted towards the required

two LGTMs.

Overall the maintainer system works because of mutual respect across the

maintainers of the project. The maintainers trust one another to make decisions

in the best interests of the project. Sometimes maintainers can disagree and

this is part of a healthy project to represent the point of views of various people.

In the case where maintainers cannot find agreement on a specific change the

role of a Chief Maintainer comes into play.

The Chief Maintainer for the project is responsible for overall architecture

of the project to maintain conceptual integrity. Large decisions and

architecture changes should be reviewed by the chief maintainer.

The current chief maintainer for the project is the first person listed

in the MAINTAINERS file.

Even though the maintainer system is built on trust, if there is a conflict

with the chief maintainer on a decision, their decision can be challenged

and brought to the technical oversight board if two-thirds of the

maintainers vote for an appeal. It is expected that this would be a

very exceptional event.

The best maintainers have a vested interest in the project. Maintainers

are first and foremost contributors that have shown they are committed to

the long term success of the project. Contributors wanting to become

maintainers are expected to be deeply involved in contributing code,

pull request review, and triage of issues in the project for more than two months.

Just contributing does not make you a maintainer, it is about building trust

with the current maintainers of the project and being a person that they can

depend on and trust to make decisions in the best interest of the project. The

final vote to add a new maintainer should be approved by over 66% of the current

maintainers with the chief maintainer having veto power. In case of a veto,

conflict resolution rules expressed above apply. The voting period is

five business days on the Pull Request to add the new maintainer.

Part of a healthy project is to have active maintainers to support the community

in contributions and perform tasks to keep the project running. Maintainers are

expected to be able to respond in a timely manner if their help is required on specific

issues where they are pinged. Being a maintainer is a time consuming commitment and should

not be taken lightly.

When a maintainer is unable to perform the required duties they can be removed with

a vote by 66% of the current maintainers with the chief maintainer having veto power.

The voting period is ten business days. Issues related to a maintainer's performance should

be discussed with them among the other maintainers so that they are not surprised by

a pull request removing them.