Workflow¶

The workflow for developing on Pedigree with git is outlined in this wiki page. This workflow must be followed in order to ease development, reduce conflicts, and most importantly: simplify releases.

The workflow is intended to also facilitate automated publishable builds and snapshots in the future.

Branches¶

There are two standard branches for the Pedigree source tree;

• master
• develop

All development work is to be done in 'develop'. Matt will move commits from develop to master as he sees fit, so that master remains stable and buildable. As a general rule the "latest" contents of master will be the tagged release that was most recently made, in order to improve hotfix creation and merging.

Initial Checkout¶

To work from an existing checkout of Pedigree, you will need to fetch and switch to the current develop branch:

git fetch
git checkout develop

A Note About Working in 'develop'¶

Working in the develop branch is straightforward: you can push changes as necessary, pull changes since your last fetch - essentially, it's open to any modification.

At no point should you be pushing 'master', or working in 'master': only Matt should be merging and pushing master.

Feature Branches¶

At some point in time you will want to work on a feature that may break existing code, could cause regressions, or is just irrelevant and noisy in the develop branch. In this case you need to create a feature branch for yourself.

Let's say you are working on a module named 'abcd' and it makes a fair few changes throughout the kernel that break someone else's module. You would do the following:

git checkout -b module_abcd develop

This creates a new branch named 'module_abcd' and refers it back to the 'develop' branch at the current commit. To update the remote repository and notify it of the new branch, use:

git push origin module_abcd

You can now work on this module anywhere you have a Pedigree source checkout by running:

git fetch
git checkout module_abcd

You may need to run

git fetch origin module_abcd

instead of just git fetch to track the remote branch.

At some point changes will be made to the develop branch while you are working on your feature. You may want one of the changes - to do so you need to merge the changes to the develop branch with your own branch:

git merge --no-ff develop

You will need to fix any conflicts that come up

At the end of development on your feature, talk to Matt about merging your changes back into the develop branch. Do not merge the changes back yourself: QA will be done on the branch before it is merged, and you may need to go back and continue development to fix issues that QA testing bring up.

Release Branches¶

Release branches are created in preparation for a specific upcoming release, to contain changes relevant to that release (and prepare for a tag to be placed onto the master branch on the date of the release). Generally speaking the release branch is created from a specific commit in the develop branch and two things are done:

• The README is updated with a new version identifier
• The greeting message for the TUI is updated.

Any further work in develop for bugfixing or other release-related work is brought into the release branch until release date, at which point the release branch is merged into master, a tag is created, and the release branch is deleted. The tag provides a snapshot of the source at a specific point in time; specifically, when the release went live.

Hotfix Branches¶

Hotfix branches originate from master, at a specific tag for the release the hotfix is for.

The only reason for hotfix branches is to fix a very specific bug that has appeared in a release that has not yet been fixed since release. Because the latest commit in master is always a tagged release, it is possible for the hotfix to be created and applied back to master as a revision of the original release (with a new tag and version number).

As per the release branches, Matt will decide whether it is time to create a hotfix branch and if so, he will create the branch for developers to work in. At the end of the hotfix development, it will be merged into master (and a tag created), as well as back into develop for future releases. A new release will be made from the new version number as a hotfix release.

The most important thing to happen in a hotfix branch is to ensure that the README is updated with the right version number and hotfix identifier. This means any checkout of the tag will be easily identifiable as a hotfix release rather than a major release.

Disclaimer¶

The documentation related to release and hotfix branches is subject to change as the workflow is adjusted (neither situations have been dealt with yet on a live repository). Any changes will be made known in the project IRC channel: #pedigree on Freenode.