XS Community Edition/5.0/Hacking
This IIAB XSCE content does not reflect the opinion of OLPC. These pages were created by members of a volunteer community supporting OLPC and deployments.
See also https://github.com/XSCE/xsce/blob/master/docs/HACKING.rst part of the larger https://github.com/XSCE/xsce/tree/master/docs
The Code
Downloading code
$ git clone --depth=1 https://github.com/XSCE/xsce <-- (Shows progress through git:// protocol)
or for commit access (requires login and password)
Please refer to "install instructions in github"
Older Design documents: Design Document, Use cases, and Release Priorities.
Original OLPC XS design and implementation available at OLPC School Server.
XSCE Git Branch Model
Main Branch
The main branch in this model is origin/master. The source code of HEAD always reflects the state of development for the next release. This can be called the “integration branch.” Commits to this branch trigger automatic builds.
Supporting Branches
In addition to the master, branch there are three types of supporting branches to aid parallel development between team members, ease tracking of features, prepare for releases and to assist in quickly fixing release issues.
The three types of branches we use are:
- Feature branches
- Testing branches
- Release branches
Feature Branches
Must branch off from: master
Must merge back into: master
Branch naming convention: anything except master or release-*
Feature branches (or topic branches) are used to develop new features for the future releases. When starting development of a feature, the target release for this release may not be known. A feature branch only exists as long as the feature is in development.
It will either be merged back into master (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment).
Feature branches typically exist only in developer repos, not in origin.
Testing Branches
Must branch off from: master
Must merge back into: master
Branch naming convention: testing-*
A new testing branched from master when the Release Manager declares the first release candidate ready. Most features that are targeted for the release should be merged into master at this point in time.
Periodically the release manager manually triggers a new release candidate build from testing .
Release Branches
Must branch off from: testing-*
Must merge back into: none
Branch naming convention: release-*
A new release is branched from testing when the Release Manager declares the release ready. All features that are targeted for the release must be merged in to develop at this point in time. All features targeted at future releases may not—they must wait until after the release branch is branched off.
The initial commit to release results in a release. Commits to release trigger automatic builds
Hotfix Branches
After final release the testing branch becomes the hotfix branch.
Hotfix branches support a specific release. They enable minor bug fixes to a release which can also be merged back to master. By doing this work on a hotfix branch, it is clear that this is a minor bugfix which is designed to fix a specific issue in a release.
Subsequent commits to testing result in point releases.
Git Workflow
Another description of the current workflow using github is at https://sugardextrose.org/projects/dxs/wiki/Git. The reader must substitute "xsce" for "dxs", but many of the concepts are closer to what is currently happening among the development team (I think --George Hunt).
Creating a feature branch
When starting work on a new feature, branch off from the master branch.
$ git checkout -b myfeature master
Switched to a new branch "myfeature"
Incorporating a finished feature on master
Finished features may be merged into the master branch to prepare them for inclusion in the upcoming release:
$ git checkout master
Switched to branch 'master'
$ git merge myfeature
Updating ea1b82a..05e9557 (Summary of changes)
$ git branch -d myfeature
Deleted branch myfeature (was 05e9557).
$ git push origin master
Creating a testing branch
Only the release manager should create a testing branch from the master branch when the state of master is ready for community testing. He creates the testing branch and gives it a name reflecting the new version number:
$ git checkout -b testing-0.3 master
Switched to a new branch "testing-0.3"
$ git tag -a 0.3
After creating a new branch and switching to it, he tags it with the version number.
Creating a release branch
Only the release manager should create a release branch from the testing branch when the state of testing is ready for the “next release.” He creates the release branch and gives it a name reflecting the new version number:
$ git checkout -b release-0.3 testing-0.3
Switched to a new branch "release-0.3"
$ git tag -a 0.3
After creating a new branch and switching to it, he tags it with the version number.
Creating a hotfix branch
After a release the testing branch becomes the hotfix branch
Incorporating a hotfix to a release
After testing, finished hotfixes may be merged into the release-* branch to prepare them for inclusion in the next point release:
$ git checkout release-0.3
Switched to branch 'release-0.3'
$ git merge testing-0.3
Updating ea1b82a..05e9557 (Summary of changes)
$ git tag -a 0.3.1
$ git push origin release-0.3
Incorporating a hotfix to master
If necessary, finished hotfixes may be merged into the master branch for inclusion in future releases:
$ git checkout master
Switched to branch 'master'
$ git merge testing
Updating ea1b82a..05e9557 (Summary of changes)
$ git push origin master