Merge pull request #451 from metamaps/feature/contributing.md.updates

Update CONTRIBUTING.md
This commit is contained in:
Devin Howard 2016-02-05 11:35:42 +08:00
commit a1d2ef70b9

View file

@ -1,84 +1,87 @@
# Contributing to Metamaps # Contributing to Metamaps
Active involvement from the community is essential to help make Metamaps as beneficial for communities as it can be. You can help by reporting bugs, fixing bugs, adding features, contributing new modules and by providing feedback. Active involvement from the community is essential to help make Metamaps as
beneficial for communities as it can be. You can help by reporting bugs, fixing
bugs, adding features, contributing new modules and by providing feedback.
## Reporting bugs and other issues ## Reporting bugs and other issues
If you think you've encountered a bug, do the following: If you think you've encountered a bug, do the following:
1. Make sure you are working with the latest version of the Metamaps `master` branch. 1. Make sure you are working with the latest version of the Metamaps `develop`
2. Browse through the [issues][metamaps-issues] to check if branch.
anyone else has already reported. If someone has, feel free to add more 2. Browse through the [issues][metamaps-issues] to check if anyone else has
information to that issue to help us solve it. already reported. If someone has, feel free to add more information to that
3. If no one has yet submitted the issue you are encountering, add it in! Please be sure issue to help us solve it.
to include as much information as possible, include errors, warnings, 3. If no one has yet submitted the issue you are encountering, add it in! Please
be sure to include as much information as possible, include errors, warnings,
screenshots, links to a video showing the problem or code that can reproduce screenshots, links to a video showing the problem or code that can reproduce
the issue. the issue.
## Contributing code ## Contributing code
Metamaps is made possible by open source Metamaps is made possible by open source contributors like you. We're very
contributors like you. We're very interested in getting help from the greater interested in getting help from the greater community, but before you start it's
community, but before you start it's important that you become acquainted with important that you become acquainted with our workflow. Following these
our workflow. Following these guidelines below will make collaboration much guidelines below will make collaboration much smoother and increase the chances
smoother and increase the chances that we will accept your pull request without that we will accept your pull request without hiccups.
hiccups.
### Development Process ### Development Process
Our development process is very similar to the approach Our development process is very similar to the approach described in the
described in the well-known article [A Successful Git Branching Model by Vincent well-known article [A Successful Git Branching Model by Vincent Driessen
Driessen][git-branching-model]. Here's an overview: ][git-branching-model]. Here's an overview:
* Our `master` branch is the branch upon which * The `master` branch is the current base for our deployed instances. This
Metamaps developers should be basing their work on. The `master` branch is not guaranteed to be stable. branch *must* remain stable and always work.
* All commits intended for `master` should take place on your own personal * The `develop` branch is the current state of development. Metamaps
fork, and be submitted via pull request when ready. developers base their work on this branch. It is not guaranteed to be
* Only maintainers can accept pull requests from forks into the core Metamaps.cc stable.
repository. * All code must be reviewed before being committed to develop or master. This
* Please squash your commits into a single commit before making a pull request. means all commits should take place on your own personal branch, and
submitted via a Github pull request when ready.
* Only maintainers can accept pull requests from forks into the core
Metamaps.cc repository.
### Getting started ### Getting started
1. Make sure you have a [GitHub account](https://github.com/signup/free) 1. Make sure you have a [GitHub account](https://github.com/signup/free)
2. [Fork metamaps][fork-metamaps] 2. [Fork metamaps][fork-metamaps]
3. Keep your fork up to date. Metamaps is a fast moving project, and things are 3. Keep your fork up to date. Metamaps is a fast moving project, and things
changing all the time. It's important that any changes you make are based on are changing all the time. It's important that any changes you make are
the most recent version of metamaps, since it's possible that something may based on the most recent version of metamaps, since it's possible that
have changed that breaks your pull request or invalidates its need. something may have changed that breaks your pull request or invalidates it.
4. Make sure you have a [Contributor License Agreement](http://caa.metamaps.cc) on file. 4. Make sure you have a [Contributor License Agreement](http://caa.metamaps.cc
) on file.
5. Read on ... 5. Read on ...
### Contributor License Agreement ### Contributor License Agreement
Before we can accept any contributions to Metamaps, we first require that all Before we can accept any contributions to Metamaps, we first require that all
individuals or companies agree to our Contributor License Agreement (CLA). The e-mail individuals or companies agree to our Contributor License Agreement (CLA). The
address used in the pull request will be used to check if a CLA has already been e-mail address used in the pull request will be used to check if a CLA has
filed, so be sure to list all email addresses that you might use to submit your already been filed, so be sure to list all email addresses that you might use to
pull requests when filling it out. Our CLA can be found [here](http://caa.metamaps.cc). submit your pull requests when filling it out. [Our CLA can be found here](
http://caa.metamaps.cc).
### Testing and Linting ### Testing and Linting
TODO Please run `rspec` in the Metamaps root directory before submitting your pull
request.
### Branch grouping tokens ### Branch grouping tokens
All pull requests submitted to Metamaps.cc should occur on a new branch. For these All pull requests submitted to Metamaps.cc should occur on a new branch. For
branches, we at metamaps use a short token indicating the nature of the branch in these branches, please use a short token indicating the nature of the branch in
question followed by a solidus (`/`) and a kebab-cased string describing the question followed by a `/` and then a very concise string describing the branch.
branch. We are using the following tokens: This isn't a very important part of the workflow, but we are currently using the
**NOTE: Not sure the above is right, but also not sure what to change it to ** following branch prefixes:
bug // bug fixes fix // bug fixes
wip // work in progress wip // work in progress (not suitable for a pull request)
feat // feature instance // (internal) Tracks customizations made to metamaps instances
feature // All other new features
Bug fixes follow a [slightly different format](#bug-fixes).
### Bug fixes ### Bug fixes
@ -87,7 +90,7 @@ If you'd like to contribute a fix for a bug you've encountered, first read up on
aware of the issue. By filing the issue first, we may be able to provide you aware of the issue. By filing the issue first, we may be able to provide you
with some insight that guides you in the right direction. with some insight that guides you in the right direction.
[metamaps-issues]: https://github.com/metamaps/metamaps_gen002/issues [metamaps-issues]: https://github.com/metamaps/metamaps_gen002/labels/bug
[git-branching-model]: http://nvie.com/posts/a-successful-git-branching-model/ [git-branching-model]: http://nvie.com/posts/a-successful-git-branching-model/
[fork-metamaps]: https://github.com/metamaps/metamaps_gen002/fork [fork-metamaps]: https://github.com/metamaps/metamaps_gen002/fork
[cla]: http://metamaps.cc/cla [cla]: http://metamaps.cc/cla