Skip to content

Home

Jump to bottom
Lars Helge Øverland edited this page Nov 18, 2016 · 30 revisions

Welcome to the DHIS 2 wiki pages.

Repository structure

The dhis2-core repository contains the following branches.

  • Master: The master branch represents the snapshot / latest development branch. Master receives commits through pull requests from feature branches and maintenance branches.
  • Stable release branches: Each stable release has a stable release branch. The stable release branches are the basis for the regular DHIS 2 releases, such as 2.23, 2.24 and so on. These branches receives bug-fixes and tweaks which are cherry-picked from master. An example of a stable release branch is 2.24.
  • Feature branches: Feature branches contains individual features. An example of feature branch could be soft-deletes.
  • Maintenance branches: Maintenance branches is owned by individual developers and contains tweakes and minor fixes. An example of a feature branch could be lars-dhis2-core.

Development workflow

This section covers the regular development workflow.

  1. Create a branch for development work. Feature branches should be created for substantial features. Give the branch a descriptive name, e.g. soft-data-value-deletes. Maintenance branches should be created for minor tweaks and cleanup. Give the branch a name on the format {dev-name}-dhis2-core, e.g. lars-dhis2-core.

  2. Do development work in the respective branch.

  3. Publish your branch. This can be done by a) pushing your branch into the main dhis2-core branch or b) push it as a separate forked repository under your personal account.

  4. Open a pull request for your feature or fix. Provide the pull request with a descriptive message.

  5. Ensure that tests are passing.

  6. Optionally, request peer review of your pull request from another core developer.

  7. Merge the pull request into master. For feature branches, do a squash merge, where a single commit is merged into master representing the entire feature. For maintenance branches you can potentially do an "expanded" commit where each individual commits are merged into master. In that case, ensure that each commit has a descriptive commit message.

Git useful commands

The following git commands are useful in the regular development workflow.

  • View all local branches: git branch
  • Pull remote changes into local branch: git pull
  • Create local branch e.g. soft-deletes: git branch soft-deletes
  • Switch to branch: git checkout soft-deletes
  • View local changes to files: git status
  • View local code diff: git diff
  • Add changes for later commit: git add -A or git add {name-of-file-or-dir}
  • Push repository or changes to Github: git push origin soft-deletes
  • Switch to master branch: git checkout master

Git commit messages

When it is time to commit, supply a descriptive commit message with less than 70 characters. To add an additional description, supply a line break after the message and then the description. This can be done by using single-quotes and line breaks on the command line and will look like this:

git commit -m 'Implemented super fast aggregation
> Enabled turbo boost switch in database.'

Squash commits from command line

After working locally on a branch you might want to squash multiple commits, i.e. combine into one. If you have e.g. two commits that you want combine into one you can do:

git rebase -i HEAD~2

On the screen that appears, leave the first line with pick as it is, then on the second line change pick to squash and save. On the next screen, edit your commit message and save. You can now merge your commit to another branch or push to remote.

Back-ports to stable branches

This section describes the workflow for back-porting bug-fixes and tweaks to stable branches.

  • Check out a stable branch e.g. 2.24 with: git checkout 2.24
  • To fetch the branch from remote (only needed once): git fetch
  • To update the branch later with remote changes: git pull
  • To pick a commit from master, find the commit hash and apply it with: git cherry-pick -x {hash}, the hash will look something like c3c1ede6cfd1f47f30490abfbdca622db1ef6259. The -x option appends cherry-picked from ... to the commit message.
  • To publish the commit to the stable release branch for e.g. 2.24 do: git push origin 2.24
Clone this wiki locally