How to Contribute

Setup

Fork on Github

Before you start, login or signup to Github and fork the Mapstory application from the Github Repository.

Clone your fork locally

Using the command line or your preferred Git Software (we like Sourcetree), clone the project that you just forked. If you're using the command line you would utilize the below command.

git clone https://github.com/<your-user-name>/mapstory-geonode.git

Installing Mapstory

Follow our Developer Setup Instructions in order to deploy Mapstory to your local machine. If you run into any issues during the process, please submit a Github Issue by following our Issue & Bug Report Guidelines.

Issues

The list of outstanding Mapstory feature requests and bugs can be found on our main repository's issue tracker. You can also browse our overall roadmap by taking a look at the Mapstory Roadmap repository. Pick an unassigned issue that you think you can accomplish, add a comment to let others know that you'll be working on it and assign the issue to yourself.

If you attempt the issue and need help, feel free to comment on the issue and bring other developers into the conversation. Never be afraid to ask for help. If you're truly stumped, let others know that you're moving on from that issue in the comments and move it back to unassigned.

Contributing Code with Topic Branches

So you've decided on an issue and you're ready to tackle it? Great! First you'll want to make sure that your fork is up to date with the upstream master branch. Assuming you're up to date, you can get started. Start by creating a topic branch and start writing your code. Make sure to follow all of our development best practices at style guides located in our Wiki when you're writing your code.

Creating a topic branch is easiest by adding the -b argument to your git checkout command.

git checkout -b your-topic-branch-name
Switched to a new branch 'your-topic-branch-name'

Make sure that you're descriptive in your branch name and you align it to the issue you're trying to solve, so that it's easier for both you and anyone reviewing your code to understand later. Make sure that you isolate your code in the topic branch you've created, and keep it specific to the issue that you're working on. It's much easier to review pull requests that are specific, tied to an issue and well tested. We'll go over all of that shortly.

Once you're happy with your code and ready to submit it, you can submit a pull request from the branch that you created on your fork. Before you do that, please make sure to read the next section about getting your pull requests accepted.

Run the Tests

The very first thing that anyone reviewing your pull request is going to do is run the suite of tests that we have provided. You can learn how to run our test suite on our Testing Wiki. Travis CI will also automatically run the tests when you submit your pull request, but please run them locally first so that you don't submit code you know will end up failing in the Travis CI build.

Add Additional Tests

If you've added any code, you'll need to write tests for it as well. Code without tests is unreliable and any pull request that reduces the overall test coverage will be automatically rejected. Keep your tests simple, and make sure that all lines of code you've added are covered.

You can refer to the Coding Style Guides and Testing documents on our Wiki for additional information on writing good tests.