Guidelines:ContributorWorkflow

• All Guidelines

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:

• git
• a suitable programming editor (e.g. Kate)

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 sahana/eden master:

Git clone with master branch

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.

Now your local clone has two branches, like this:

Creating Story Branches

Rather than making changes in the dev branch directly, you should use a new branch for every set of changes you make, a so-called story branch.

To create a new story branch, change into your eden folder, and checkout the dev branch:

 git checkout dev

From this, create the new story branch:

 git checkout -b story_branch

...replacing story_branch with a descriptive name for the change set (e.g. bugfix_org_menu).

Make your changes to the story branch, and test-run and verify them with your local instance.

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, 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.

Publishing Changes

To get your changes merged into Sahana Eden, start by committing them to the story branch:

 git checkout story_branch
 git commit -a

Before publishing the changes, it may be necessary that you 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

...and then rebase your story branch on it:

 git checkout story_branch
 git rebase dev

Finally, publish your changes by pushing them to your GitHub repo:

 git push origin story_branch

This will copy the story branch to your repository on GitHub, or update that branch there if it already exists.

Submitting Pull Requests

To get your changes merged into the main Sahana Eden repository, you need to submit a pull request. Follow the GitHub documentation to create a pull request.

Make sure that you compare:

• your story branch (head repository)
• against the sahana/eden dev branch (base repository)

Create a pull request (rather than a draft pull request) to submit your changes for review. Anyone can comment on your pull request, and you can discuss with them directly on GitHub.

If you need to modify your changes in order to get them accepted, make the modifications locally, commit them and push to your story branch again:

 git checkout story_branch
 git commit -a
 git push origin story_branch

This will automatically update your pull request with the new commit.

Eventually, a maintainer will decide whether to accept and merge your changes, or to reject them.

Once they 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

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.