umgeher/cowboy
0
Fork 0
mirror of https://github.com/ninenines/cowboy.git synced 2025-07-14 04:10:24 +00:00
Code Issues Wiki Activity

Update the CONTRIBUTING file

Browse source 
Looks like I pushed too early in the previous commit. Oops!
This commit is contained in:
Loïc Hoguin 2015-07-25 12:22:39 +02:00
parent d2924de2b6
commit 73cd4458c3
1 changed files with 268 additions and 123 deletions
Download patch file Download diff file Expand all files Collapse all files

391
CONTRIBUTING.asciidoc
View file

@ -1,173 +1,318 @@
Contributing
============
= Contributing
Introduction
------------
This document is a guide on how to best contribute to this project.
This document describes the usages and rules to follow when contributing
to this project.
== Definitions
It uses the uppercase keywords SHOULD for optional but highly recommended
conditions and MUST for required conditions.
*SHOULD* describes optional steps. *MUST* describes mandatory steps.
`git` is a distributed source code versioning system. This document refers
to three different repositories hosting the source code of the project.
`Your local copy` refers to the copy of the repository that you have on
your computer. The remote repository `origin` refers to your fork of the
project's repository that you can find in your GitHub account. The remote
repository `upstream` refers to the official repository for this project.
*SHOULD NOT* and *MUST NOT* describes pitfalls to avoid.
Following this document will ensure prompt merging of your work in the
`master` branch of the project.
_Your local copy_ refers to the copy of the repository that you have
on your computer. _origin_ refers to your fork of the project. _upstream_
refers to the official repository for this project.
Reporting bugs
--------------
== Discussions
Upon identifying a bug or a DoS vulnerability, you SHOULD submit a ticket,
regardless of your plans for fixing it. If you plan to fix the bug, you
SHOULD discuss your plans to avoid having your work rejected.
For general discussion about this project, please open a ticket.
Feedback is always welcome and may transform in tasks to improve
the project, so having the discussion start there is a plus.
Upon identifying a security vulnerability in Erlang/OTP that leaves Cowboy
vulnerable to attack, you SHOULD consult privately with the Erlang/OTP team
to get the issue resolved.
Alternatively you may try the #ninenines IRC channel on Freenode,
or, if you need the discussion to stay private, you can send an
email at contact@ninenines.eu.
Upon identifying a security vulnerability in Cowboy's `cowboy_static` module,
you SHOULD submit a ticket, regardless of your plans for fixing it. Please
ensure that all necessary details to reproduce are listed. You then SHOULD
inform users on the mailing list about the issue, advising that they use
another means for sending static files until the issue is resolved.
== Support
Upon identifying a security vulnerability in any other part of Cowboy, you
SHOULD contact us directly by email. Please ensure that all necessary details
to reproduce are listed.
Free support is generally not available. The rule is that free
support is only given if doing so benefits most users. In practice
this means that free support will only be given if the issues are
due to a fault in the project itself or its documentation.
Before implementing a new feature, you SHOULD submit a ticket for discussion
on your plans. The feature might have been rejected already, or the
implementation might already be decided.
Paid support is available for all price ranges. Please send an
email to contact@ninenines.eu for more information.
Cloning
-------
== Bug reports
You MUST fork the project's repository to your GitHub account by clicking
on the `Fork` button.
You *SHOULD* open a ticket for every bug you encounter, regardless
of the version you use. A ticket not only helps the project ensure
that bugs are squashed, it also helps other users who later run
into this issue.
Then, from your fork's page, copy the `Git Read-Only` URL to your clipboard.
You MUST perform the following commands in the folder you choose, replacing
`$URL` by the URL you just copied, `$UPSTREAM_URL` by the `Git Read-Only`
project of the official repository, and `$PROJECT` by the name of this project.
You *SHOULD NOT* open a ticket if another already exists for the
same issue. You *SHOULD* instead either add more information by
commenting on it, or simply comment to inform the maintainer that
you are also affected. The maintainer *SHOULD* reply to every
new ticket when they are opened. If the maintainer didn't say
anything after a few days, you *SHOULD* write a new comment asking
for more information.
``` bash
$ git clone "$URL"
When you have a fix ready, you *SHOULD* open a pull request,
even if the code does not fit the requirements discussed below.
Providing a fix, even a dirty one, can help other users and/or
at least get the maintainer on the right tracks.
== Security reports
You *SHOULD* open a ticket when you identify a DoS vulnerability
in this project. You *SHOULD* include the resources needed to
DoS the project; every project can be brought down if you have
the necessary resources.
You *SHOULD* send an email to contact@ninenines.eu when you
identify a security vulnerability. If the vulnerability originates
from code inside Erlang/OTP itself, you *SHOULD* also consult
with OTP Team directly to get the problem fixed upstream.
== Feature requests
Feature requests are always welcome. To be accepted, however, they
must be well defined, make sense in the context of the project and
benefit most users.
Feature requests not benefiting most users may only be accepted
when accompanied with a proper pull request.
You *MUST* open a ticket to explain what the new feature is, even
if you are going to submit a pull request for it.
All these conditions are meant to ensure that the project stays
lightweight and maintainable.
== Documentation submissions
You *SHOULD* follow the code submission guidelines to submit
documentation.
The documentation is available in the 'doc/src/' directory. There
are three kinds of documentation: manual, guide and tutorials. The
format for the documentation is Asciidoc.
You *SHOULD* follow the same style as the surrounding documentation
when editing existing files.
You *MUST* include the source when providing media.
== Examples submissions
You *SHOULD* follow the code submission guidelines to submit examples.
The examples are available in the 'examples/' directory.
You *SHOULD* focus on exactly one thing per example.
== Code submissions
You *SHOULD* open a pull request to submit code.
You *SHOULD* open a ticket to discuss backward incompatible changes
before you submit code. This step ensures that you do not work on
a large change that will then be rejected.
You *SHOULD* send your code submission using a pull request on GitHub.
If you can't, please send an email to contact@ninenines.eu with your
patch.
The following sections explain the normal GitHub workflow.
=== Cloning
You *MUST* fork the project's repository on GitHub by clicking on the
_Fork_ button.
On the right page of your fork's page is a field named _SSH clone URL_.
Its contents will be identified as `$ORIGIN_URL` in the following snippet.
On the right side of the project's repository page is a similar field.
Its contents will be identified as `$UPSTREAM_URL`.
Finally, `$PROJECT` is the name of this project.
To setup your clone and be able to rebase when requested, run the
following commands:
[source,bash]
$ git clone $ORIGIN_URL
$ cd $PROJECT
$ git remote add upstream $UPSTREAM_URL
```
Branching
---------
=== Branching
Before starting working on the code, you MUST update to `upstream`. The
project is always evolving, and as such you SHOULD always strive to keep
up to date when submitting patches to make sure they can be merged without
conflicts.
You *SHOULD* base your branch on _master_, unless your patch applies
to a stable release, in which case you need to base your branch on
the stable branch, for example _1.0.x_.
To update the current branch to `upstream`, you can use the following commands.
The first step is therefore to checkout the branch in question:
``` bash
[source,bash]
$ git checkout 1.0.x
The next step is to update the branch to the current version from
_upstream_. In the following snippet, replace _1.0.x_ by _master_
if you are patching _master_.
[source,bash]
$ git fetch upstream
$ git rebase upstream/master
```
$ git rebase upstream/1.0.x
It may ask you to stash your changes, in which case you stash with:
This last command may fail and ask you to stash your changes. When
that happens, run the following sequence of commands:
``` bash
[source,bash]
$ git stash
```
And put your changes back in with:
``` bash
$ git rebase upstream/1.0.x
$ git stash pop
```
You SHOULD use these commands both before working on your patch and before
submitting the pull request. If conflicts arise it is your responsability
to deal with them.
The final step is to create a new branch you can work in. The name
of the new branch is up to you, there is no particular requirement.
Replace `$BRANCH` with the branch name you came up with:
You MUST create a new branch for your work. First, ensure you are on `master`.
You MUST update `master` to `upstream` before doing anything. Then create a
new branch `$BRANCH` and switch to it.
``` bash
[source,bash]
$ git checkout -b $BRANCH
```
You MUST use a an insightful branch name.
_Your local copy_ is now ready.
If you later need to switch back to an existing branch `$BRANCH`, you can use:
=== Source editing
``` bash
$ git checkout $BRANCH
```
There are very few rules with regard to source code editing.
Source editing
--------------
You *MUST* use horizontal tabs for indentation. Use one tab
per indentation level.
The following rules MUST be followed:
* Indentation uses horizontal tabs (1 tab = 4 columns)
* Do NOT align code; only indentation is allowed
* Lines MUST NOT span more than 80 columns
You *MUST NOT* align code. You can only add or remove one
indentation level compared to the previous line.
The following rules SHOULD be followed:
* Write small functions whenever possible
* Avoid having too many clauses containing clauses containing clauses
You *SHOULD NOT* write lines more than about a hundred
characters. There is no hard limit, just try to keep it
as readable as possible.
Committing
----------
You *SHOULD* write small functions when possible.
You MUST ensure that all commits pass all tests and do not have extra
Dialyzer warnings.
You *SHOULD* avoid a too big hierarchy of case clauses inside
a single function.
Running tests is fairly straightforward. Note that you need at least
Erlang/OTP R16B01 for the SSL tests to run.
You *SHOULD* add tests to make sure your code works.
``` bash
make tests
```
=== Committing
Running Dialyzer requires some initial setup. You need to build the PLT
file that Dialyzer will use for its analysis. This is a one-time operation.
Dialyzer will take care of updating that file when needed.
You *SHOULD* run Dialyzer and the test suite while working on
your patch, and you *SHOULD* ensure that no additional tests
fail when you finish.
``` bash
make build-plt
```
You can use the following command to run Dialyzer:
Once that is done, you can run Dialyzer.
[source,bash]
$ make dialyze
``` bash
make dialyze
```
You have two options to run tests. You can either run tests
across all supported Erlang versions, or just on the version
you are currently using.
You MUST put all the related work in a single commit. Fixing a bug is one
commit, adding a feature is one commit, adding two features is two commits.
To test across all supported Erlang versions:
You MUST write a proper commit title and message. The commit title MUST be
at most 72 characters; it is the first line of the commit text. The second
line of the commit text MUST be left blank. The third line and beyond is the
commit message. You SHOULD write a commit message. If you do, you MUST make
all lines smaller than 80 characters. You SHOULD explain what the commit
does, what references you used and any other information that helps
understanding your work.
[source,bash]
$ make -k ci
Submitting the pull request
---------------------------
To test using the current version:
You MUST push your branch `$BRANCH` to GitHub, using the following command:
[source,bash]
$ make tests
``` bash
You can then open Common Test logs in 'logs/all_runs.html'.
Once all tests pass (or at least, no new tests are failing),
you can commit your changes.
First you need to add your changes:
[source,bash]
$ git add src/file_you_edited.erl
If you want an interactive session, allowing you to filter
out changes that have nothing to do with this commit:
[source,bash]
$ git add -p
You *MUST* put all related changes inside a single commit. The
general rule is that all commits must pass tests. Fix one bug
per commit. Add one feature per commit. Separate features in
multiple commits only if smaller parts of the feature make
sense on their own.
Finally once all changes are added you can commit. This
command will open the editor of your choice where you can
put a proper commit title and message.
[source,bash]
$ git commit
Do not use the `-m` option as it makes it easy to break the
following rules:
You *MUST* write a proper commit title and message. The commit
title is the first line and *MUST* be at most 72 characters.
The second line *MUST* be left blank. Everything after that is
the commit message. You *SHOULD* write a detailed commit
message. The lines of the message *MUST* be at most 80 characters.
You *SHOULD* explain what the commit does, what references you
used and any other information that helps understanding why
this commit exists. You *MUST NOT* include commands to close
GitHub tickets automatically.
=== Cleaning the commit history
If you create a new commit every time you make a change, however
insignificant, you *MUST* consolidate those commits before
sending the pull request.
This is done through _rebasing_. The easiest way to do so is
to use interactive rebasing, which allows you to choose which
commits to keep, squash, edit and so on. To rebase, you need
to give the original commit before you made your changes. If
you only did two changes, you can use the shortcut form `HEAD^^`:
[source,bash]
$ git rebase -i HEAD^^
=== Submitting the pull request
You *MUST* push your branch to your fork on GitHub. Replace
`$BRANCH` with your branch name:
[source,bash]
$ git push origin $BRANCH
```
You MUST then submit the pull request by using the GitHub interface.
You SHOULD provide an explanatory message and refer to any previous ticket
related to this patch.
You can then submit the pull request using the GitHub interface.
You *SHOULD* provide an explanatory message and refer to any
previous ticket related to this patch. You *MUST NOT* include
commands to close other tickets automatically.
=== Updating the pull request
Sometimes the maintainer will ask you to change a few things.
Other times you will notice problems with your submission and
want to fix them on your own.
In either case you do not need to close the pull request. You
can just push your changes again and, if needed, force them.
This will update the pull request automatically.
[source,bash]
$ git push -f origin $BRANCH
=== Merging
This is an open source project maintained by independent developers.
Please be patient when your changes aren't merged immediately.
All pull requests run through a Continuous Integration service
to ensure nothing gets broken by the changes submitted.
Bug fixes will be merged immediately when all tests pass.
The maintainer may do style changes in the merge commit if
the submitter is not available. The maintainer *MUST* open
a new ticket if the solution could still be improved.
New features and backward incompatible changes will be merged
when all tests pass and all other requirements are fulfilled.