Guidelines:DeveloperWorkflow

• All Guidelines

Developer Workflow

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. To get a copy of that branch into your local clone, change into the eden folder and run these 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.

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 publish your changes, commit them to the story branch:

 git checkout story_branch
 git commit -a

...and then push that branch 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.

It may be necessary that you rebase your story branch on a newer 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, and push to your remote story branch again to update the pull request:

 git checkout story_branch
 git rebase dev

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