View source for Guidelines:ContributorWorkflow

* [[Guidelines:Index|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 ===

You should have the following installed on your computer:

* [https://git-scm.com '''git''']
* a suitable programming editor (e.g. [https://kate-editor.org Kate])

=== Forking Sahana Eden ===

Start by creating your own fork of '''Sahana Eden''':
* Login to [https://github.com|'''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''<sup>*</sup>, which is your own copy of ''sahana/eden'' - and the repository you will work on.

<sup>*</sup> ''[yourname] here stands for your GitHub username''

=== Creating a Local Clone ===

Follow the steps in the [https://eden-asp.readthedocs.io/en/latest/dev/setup.html '''Developer Handbook'''] to set up a local instance of Sahana Eden. You will use this local instance to test-run and verify your changes.

When you get to [https://eden-asp.readthedocs.io/en/latest/dev/setup.html#installing-eden '''Installing Eden'''], make sure to clone '''your own fork''':

  <nowiki>git clone --recursive https://github.com/[yourname]/eden.git ~/eden</nowiki>

...instead of ''sahana/eden.git''.

Finally, configure ''sahana/eden.git'' as upstream repository for your clone:

  <nowiki>git remote add upstream https://github.com/sahana/eden.git</nowiki>

=== Adding the Development Branch ===

All development should be based on the <code>dev</code> branch of ''sahana/eden''.

Initially, your local clone will only contain the <code>master</code> branch, which is a copy of the latest stable version (= sahana/eden <code>master</code>):

[[File:Clone with master.png|frame|center|Git clone with master branch]]

To add a copy of the <code>dev</code> branch, use the following two commands:

  git checkout -b dev
  git pull upstream dev

This adds a copy of the Sahana Eden <code>dev</code> 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):

[[File:Clone with dev branch.png|frame|center]]

=== 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:
[[File:Clone with story branch.png|frame|center]]

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 were working on your story branch, the upstream <code>dev</code> branch may have progressed with commits from other people. Therefore, it will become necessary that you occasionally rebase your <code>story</code> branch on the latest version of the upstream <code>dev</code> branch.

To do so, first update your local <code>dev</code> branch:

  git checkout dev
  git pull upstream dev

Now your local clone will have a new ''HEAD'' for the <code>dev</code> branch:
[[File:Clone before rebase.png|frame|center]]

To rebase your <code>story</code> branch, use the following commands:

  git checkout story
  git rebase dev

Now, your <code>story</code> branch will be ahead of the <code>dev</code> branch again:
[[File:Clone rebased.png|frame|center]]

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 <code>story</code> 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.

[[File:Clone before merge.png|frame|center]]

To get your changes merged into the upstream <code>dev</code> branch (i.e. the main development branch of the project), you need to submit a '''pull request'''. 

&rarr; Remember to publish the latest version of your <code>story</code> branch before creating a pull request &larr;

Follow the [https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork GitHub documentation] to create the pull request.

Make sure that you compare:

* your <code>story</code> branch in your GitHub repository ('''head''' repository)
* against the <code>dev</code> branch 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 <code>story</code> 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 <code>dev</code> 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
  git push -d origin story

Now, your local clone has two branches again - with your commits from the <code>story</code> branch merged into the <code>dev</code> branch:
[[File:Clone merged.png|frame|center]]

...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:Blueprint|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.