Guidelines:ContributorWorkflow
Git Workflow for Code Contributions
This page gives and overview over the workflow for contributing code to the Sahana Eden code base.
Please note that this is just a general outline - for more details on how to work with git or GitHub, please refer to their respective documentations.
Prerequisites
Additionally, you will need:
Forking Sahana Eden
Start by creating your own fork of Sahana Eden:
- Login to GitHub (create yourself an account, if you don't have one yet)
- Navigate to https://github.com/sahana/eden
- Click on the Fork button, and follow the instructions to create a new fork
This will create a new GitHub repository [yourname]/eden*, which is your own copy of sahana/eden - and the repository you will work on.
* [yourname] here stands for your GitHub username
Creating a Local Clone
Follow the steps in the Developer Handbook to set up a local instance of Sahana Eden.
When you get to Installing Eden, make sure to clone your own fork:
git clone --recursive https://github.com/[yourname]/eden.git ~/eden
...instead of sahana/eden.
Finally, configure sahana/eden as upstream repository for your clone:
git remote add upstream https://github.com/sahana/eden.git
Now you can use this local instance to test-run and verify your changes.
Adding the Development Branch
All development should be based on the dev branch of sahana/eden.
Initially, your local clone will only contain the master branch, which is a copy of the latest stable version (= sahana/eden master):
To add a copy of the dev branch, use the following two commands:
git checkout -b dev git pull upstream dev
This adds a copy of the Sahana Eden dev branch to your local clone, and checks out the latest developer version of the code (which is usually a number of commits ahead of the stable version).
Now your local clone has two branches, like this:
Creating Story Branches
Rather than making changes in the dev branch directly, you should create a new branch for every set of changes you make, a so-called story branch.
To create a story branch, switch the dev branch of your local clone:
git checkout dev
From this, create the story branch:
git checkout -b story
...replacing story with a descriptive name for the change set (e.g. bugfix_org_menu).
Make your changes, test-run and verify them with your local instance, then commit them to the story branch:
git commit -a
When prompted for a commit message, enter a brief but meaningful description of the changes you made.
Now your local clone has three branches, like this:
You can have multiple story branches, and switch between them. However, remember that you should either stash or commit your changes before switching branches. Further, if you make changes to data models, only the story branch will have them - so it will become necessary to reset the database of your local instance when switching branches.
Rebasing Story Branches
While you are working on your story branch, the upstream dev branch may have progressed with commits from other people. Therefore, it will become necessary that you occasionally rebase your story branch on the latest version of the upstream dev branch.
To do so, first update your local dev branch:
git checkout dev git pull upstream dev
Now your local clone will have a new HEAD for the dev branch:
To rebase your story branch, use the following commands:
git checkout story git rebase dev
Now, your story branch will be ahead of the dev branch again:
You should do this in between commits to your story branch, so that you can catch and fix any conflicts or incompatibilities as early as possible. In any case, you must rebase before submitting a pull request.
Publishing Changes
You can publish your changes like this:
git checkout story git push origin story
This command will copy the story branch to your repository on GitHub, or update that branch there if it already exists.
Submitting Pull Requests
Eventually, you will want your changes merged into the dev branch.
To get your changes merged into the upstream dev branch (i.e. the main development branch of the project), you need to submit a pull request.
→ Remember to publish the latest version of your story branch before creating a pull request ←
Follow the GitHub documentation to create the pull request.
Make sure that you compare:
- your
storybranch in your GitHub repository (head repository) - against the
devbranch in the sahana/eden repository (base repository)
Anyone can comment on your pull request, and you can discuss their feedback with them directly on GitHub. However, before your changes can be merged into the upstream repository, they will have to pass a formal review by a maintainer of that repository.
There may be issues to be resolved, or details to be improved upon. If you thus need to modify your pull request again in order to pass the review, make the modifications locally, commit them to your story branch, and then simply push again to update your pull request:
git checkout story git commit -a git push origin story
Eventually, the maintainer will decide whether to accept and merge your changes, or to reject them.
Once your changes have been merged successfully into the sahana/eden dev branch, you can update your local copy of it:
git checkout dev git pull upstream dev
You can also discard your story branch:
git branch -d story_branch git push -d origin story_branch
Now, your local clone has two branches again - with your commits from the story branch merged into the dev branch:
...and you can work on a new story branch.
Best Practices
Story Branches
While you could commit your changes directly to your dev branch and create a pull request from there, we strongly advise against that practice. Unless you are working only on one small change, and do not intend to reuse your local instance for further work any time soon, you should be working in story branches.
Separating Topics
A pull request should only deal with one set of changes that are closely related to each other. If you are working on multiple topics, or complex change sets that touch many areas, you should separate these into multiple pull requests. Pull requests that are too large or complex to be meaningfully reviewed, can be rejected for that reason alone - therefore: make it coherent and digestible.
This may not always be possible: if you are e.g. creating a new template or theme, the first working version of it may involve many new files at once. In such cases, it can make sense to discuss it beforehand on the mailing list, and to provide a demo, or at least some screenshots, to aid the reviewer. Such larger change sets always require a Blueprint to get accepted.
Testing Your Code
When you submit a pull request, we expect that you have test-run the new or modified code and verified that it works correctly as intended. If a pull request contains obvious programming mistakes or design flaws that prevent it from working at all, we will reject the pull request outright.
Experimental Code
Code changes proposed in pull requests should be fully working and fulfilling their purpose. Experimental changes will normally be rejected.
If you want to discuss an idea before investing more time to make it actually work, or share some incomplete changes with fellow developers for them to continue the work, you can do so by publishing your story branch and pointing to it in a mailing list discussion. Other developers can then pull the experimental changes directly from your fork repository - so there is no need to exchange such code via the sahana/eden dev branch.
However, sometimes you may want to publish a preview version of a new feature, in order to get feedback from users or fellow developers before continuing the work. In such cases, you should mark your pull request with UAT (=user acceptance testing) to indicate your intention. For UAT, change sets can be incomplete, but they should work at least so that they can be tested. It is also required that UAT-stage feature sets are disabled by default, typically using a deployment setting.