XS Community Edition/0.4/Hacking: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
No edit summary
Line 3: Line 3:
==Downloading code==
==Downloading code==


'''$ git clone http://dev.sugardextrose.org/xs-config'''
<code>$ git clone http://dev.sugardextrose.org/xs-config</code>


'''$ git clone git://dev.sugardextrose.org/xs-config''' <-- (Shows progress through git:// protocol)
<code>$ git clone git://dev.sugardextrose.org/xs-config</code> <-- (Shows progress through git:// protocol)


or for commit access (requires login and password)
or for commit access (requires login and password)


'''$ git clone http://dev.sugardextrose.org/git/xs-config'''
<code>$ git clone http://dev.sugardextrose.org/git/xs-config</code>


==Code layout==
==Code layout==
Line 32: Line 32:


=Building=
=Building=
'''$ make rpm'''
<code>$ make rpm</code>


=XSCE Git Branch Model=


==Main Branch==
=Git Worflow=

==XS-CE 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.
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
==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.
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.


Line 53: Line 47:
* Release branches
* Release branches


Feature branches
===Feature Branches===
Must branch off from: master
Must branch off from: master
Must merge back into: master
Must merge back into: master
Line 60: Line 54:
Feature branches typically exist only in developer repos, not in origin.
Feature branches typically exist only in developer repos, not in origin.


Testing branches
===Testing Branches===
Must branch off from: master
Must branch off from: master
Must merge back into: master
Must merge back into: master
Line 67: Line 61:
Periodically the release manager manually triggers a new release candidate build from testing .
Periodically the release manager manually triggers a new release candidate build from testing .


Release branches
===Release Branches===
Must branch off from: testing-*
Must branch off from: testing-*
Must merge back into: none
Must merge back into: none
Line 74: Line 68:
The inital commit to release results in a release. Commits to release trigger automatic builds
The inital commit to release results in a release. Commits to release trigger automatic builds


Hotfix Branches
===Hotfix Branches===

After final release the testing branch becomes the hotfix branch.
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.
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.
Subsequent commits to testing result in point releases.


=Git Workflow=
Creating a feature branch
==Creating a feature branch==
When starting work on a new feature, branch off from the master branch.
When starting work on a new feature, branch off from the master branch.
$ git checkout -b myfeature master
$ git checkout -b myfeature master
Switched to a new branch "myfeature"
Switched to a new branch "myfeature"


Incorporating a finished feature on master
==Incorporating a finished feature on master==
Finished features may be merged into the master branch to prepare them for inclusion in the upcoming release:
Finished features may be merged into the master branch to prepare them for inclusion in the upcoming release:
$ git checkout master
$ git checkout master
Line 96: Line 90:
$ git push origin master
$ git push origin master


Creating a testing branch
==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:
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
$ git checkout -b testing-0.3 master
Line 103: Line 97:
After creating a new branch and switching to it, he tags it with the version number.
After creating a new branch and switching to it, he tags it with the version number.


Creating a release branch
==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:
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
$ git checkout -b release-0.3 testing-0.3
Line 110: Line 104:
After creating a new branch and switching to it, he tags it with the version number.
After creating a new branch and switching to it, he tags it with the version number.


Creating a hotfix branch
==Creating a hotfix branch==
After a release the testing branch becomes the hotfix branch
After a release the testing branch becomes the hotfix branch

Incorporating a hotfix to a release
==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:
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
$ git checkout release-0.3
Line 122: Line 117:
$ git push origin release-0.3
$ git push origin release-0.3


Incorporating a hotfix to master
==Incorporating a hotfix to master==
If necessary, finished hotfixes may be merged into the master branch for inclusion in future releases:
If necessary, finished hotfixes may be merged into the master branch for inclusion in future releases:
$ git checkout master
$ git checkout master

Revision as of 20:40, 22 June 2013

The Code

Downloading code

$ git clone http://dev.sugardextrose.org/xs-config

$ git clone git://dev.sugardextrose.org/xs-config <-- (Shows progress through git:// protocol)

or for commit access (requires login and password)

$ git clone http://dev.sugardextrose.org/git/xs-config

Code layout

The 0.3 revision of XSCE software has been made more modular.

Configuration consists of a series of scripts in the plugins.d tree. Major services are separated under plugins.d. The layout of each plugin is described in http://schoolserver.wordpress.com/xs-installation/add-a-service-to-school-server-by-creating-a-plugin/.

In the 0.2 release, the code lived in the xs-config/ dir. Consider these 3 subdirectories of xs-config:

  1. scripts/

Configuration consists of a series of scripts which live in the scripts/ dir. The process is kicked off by running xs-setup. xs-setup calls a series of scripts with the naming convention the xs-[ServiceName] each of which set up an individual service.

  1. cfg/etc/

When necessary, the xs-[ServiceName] scripts installs files from under cfg/etc as necessary.

  1. cfg/html/top/

The web based GUI is located under cfg/html/top/

Building

$ make rpm

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 inital 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

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