Replaces CONTRIBUTE file with CONTRIBUTING.md file.
The list of contributors is no longer included, as it can be deduced from the git commit history. No need to maintain it twice.pull/4/head
parent
f43e6bd89c
commit
67221add2e
|
@ -0,0 +1,79 @@
|
||||||
|
## Contribution guidelines.
|
||||||
|
|
||||||
|
So you wish to contribute to this project? Fantastic!
|
||||||
|
Here are a few guidelines to help you do this in a
|
||||||
|
streamlined fashion.
|
||||||
|
|
||||||
|
|
||||||
|
## Bug reports
|
||||||
|
|
||||||
|
When supplying a bug report, please consider the following guidelines.
|
||||||
|
These serve to make it easier for us to address the issue and find a solution.
|
||||||
|
Most of these are pretty self-evident, but sometimes it is still necessary
|
||||||
|
to reiterate them.
|
||||||
|
|
||||||
|
* Be clear in the way you express the problem. Use simple language and
|
||||||
|
just enough of it to clearly define the issue. Not everyone is a native
|
||||||
|
English speaker. And while most can handle themselves pretty well,
|
||||||
|
it helps to stay away from more esoteric vocabulary.
|
||||||
|
|
||||||
|
Be patient with non-native English speakers. If their bug reports
|
||||||
|
or comments are hard to understand, just ask for clarification.
|
||||||
|
Do not start guessing at their meaning, as this may just lead to
|
||||||
|
more confusion and misunderstandings.
|
||||||
|
* Clearly define any information which is relevant to the problem.
|
||||||
|
This includes library versions, operating system and any other
|
||||||
|
external dependencies which may be needed.
|
||||||
|
* Where applicable, provide a step-by-step listing of the way to
|
||||||
|
reproduce the problem. Make sure this is the simplest possible
|
||||||
|
way to do so. Omit any and all unneccesary steps, because they may
|
||||||
|
just complicate our understanding of the real problem.
|
||||||
|
If need be, create a whole new code project on your local machine,
|
||||||
|
which specifically tries to create the problem you are running into;
|
||||||
|
nothing more, nothing less.
|
||||||
|
|
||||||
|
Include this program in the bug report. It often suffices to paste
|
||||||
|
the code in a [Gist](https://gist.github.com) or on the
|
||||||
|
[Go playground](http://play.golang.org).
|
||||||
|
* If possible, provide us with a listing of the steps you have already
|
||||||
|
undertaken to solve the problem. This can save us a great deal of
|
||||||
|
wasted time, trying out solutions you have already covered.
|
||||||
|
|
||||||
|
|
||||||
|
## Pull requests
|
||||||
|
|
||||||
|
Bug reports are great. Supplying fixes to bugs is even better.
|
||||||
|
When submitting a pull request, the following guidelines are
|
||||||
|
good to keep in mind:
|
||||||
|
|
||||||
|
* `go fmt`: **Always** run your code through `go fmt`, before
|
||||||
|
committing it. Code has to be readable by many different
|
||||||
|
people. And the only way this will be as painless as possible,
|
||||||
|
is if we all stick to the same code style.
|
||||||
|
|
||||||
|
Some of our projects may have automated build-servers hooked up
|
||||||
|
to commit hooks. These will vet any submitted code and determine
|
||||||
|
if it meets a set of properties. One of which is code formatting.
|
||||||
|
These servers will outright deny a submission which has not been
|
||||||
|
run through `go fmt`, even if the code itself is correct.
|
||||||
|
|
||||||
|
We try to maintain a zero-tolerance policy on this matter,
|
||||||
|
because consistently formatted code makes life a great deal
|
||||||
|
easier for everyone involved.
|
||||||
|
* Commit log messages: When committing changes, do so often and
|
||||||
|
clearly -- Even if you have changed only 1 character in a code
|
||||||
|
comment. This means that commit log messages should clearly state
|
||||||
|
exactly what the change does and why. If it fixes a known issue,
|
||||||
|
then mention the issue number in the commit log. E.g.:
|
||||||
|
|
||||||
|
> Fixes return value for `foo/boo.Baz()` to be consistent with
|
||||||
|
> the rest of the API. This addresses issue #32
|
||||||
|
|
||||||
|
Do not pile a lot of unrelated changes into a single commit.
|
||||||
|
Pick and chose only those changes for a single commit, which are
|
||||||
|
directly related. We would much rather see a hundred commits
|
||||||
|
saying nothing but `"Runs go fmt"` in between any real fixes
|
||||||
|
than have these style changes embedded in those real fixes.
|
||||||
|
It creates a lot of noise when trying to review code.
|
||||||
|
|
||||||
|
|
11
CONTRIBUTORS
11
CONTRIBUTORS
|
@ -1,11 +0,0 @@
|
||||||
# This is the list of people who can contribute (or have contributed) to this
|
|
||||||
# project. This includes code, documentation, testing, content creation and
|
|
||||||
# bugfixes.
|
|
||||||
#
|
|
||||||
# Names should be added to this file like so:
|
|
||||||
# Name [<email address>]
|
|
||||||
#
|
|
||||||
# Please keep the list sorted.
|
|
||||||
|
|
||||||
Alan Shreve <alan@inconshreveable.com>
|
|
||||||
Jim Teeuwen <jimteeuwen at gmail dot com>
|
|
Loading…
Reference in New Issue