This section describes the general procedures involved in the development process.
This section assumes that a developer has:
A developer should also be relatively comfortable with the shell.
The version control system used by the project is git
. Using git provides a developer with a way to cleanly keep track of and organize their changes, in addition to the ability (among many others) to view and reapply changes made to the code at various points in time. Importantly, git meshes in a way conducive to the ONOS code submission/review process; therefore, it is important for a potential contributor to be fairly comfortable with using it. Those interested in familiarizing themselves with git may find many resources online, including a fully online book.
As git is extremely rich in features, only the relevant functions will be mentioned where they are needed.
Create and switch to a new branch. A branch is a divergence point from the existing code base. Any changes made in a branch are restricted to the branch.
$ cd $ONOS_ROOT $ git checkout -b myBranch Switched to a new branch 'myBranch' |
this creates a new branch named 'myBranch', off of the previous branch that we were in. This command will fail if there was already a branch of the same name. The command git branch
can be used to list all of the branches to check that the name isn't already used. If a branch with the desired name is no longer needed, it may be deleted with git branch -D <branchName>
and the above commands repeated to re-create a new branch.
git status
allows one to view the files that were modified. git add <file>
adds a file to the pool to commit. Once all files are added, git commit -m "<message>"
creates a snapshot with <message> as its description. git log
may be used to list all of the commits that have been made, with the most recent commit at top.Pull upstream changes. The repository on the development machine should be synchronized with the upstream ONOS source repository.
Upstream changes are always applied to the master branch. We first switch back to master with git checkout
, before pulling downloading the changes in the upstream source repository with git pull
:
$ git checkout master Switched to branch 'master' $ git pull origin master |
Sync the branch with updated master. The updates pulled to master must be explicitly applied to the branch intended for code review. This is done by switching back to the development branch and using git rebase
.
$ git checkout -b myBranch Switched to branch 'myBranch' $ git rebase -i master |
The default editor will be opened with the list of commits that have been made to the branch locally since its creation. Saving and closing this file causes the changes from the master branch to be incorporated into the branch. Any merge conflicts (e.g. a file modified in both the local and master branch) will interrupt the process. In git status
, the conflicting files will appear under "Unmerged paths" as "both modified". If this happens, the file(s) must be edited and committed before the rebase is continued:
$ git rebase -i master error: could not apply ca081b6... Initial commit for information persistence. $ vim core/net/src/main/java/org/onlab/onos/net/device/impl/DeviceManager.java $ git add core/net/src/main/java/org/onlab/onos/net/device/impl/DeviceManager.java $ git commit$ git rebase --continue Successfully rebased and updated refs/heads/myBranch. |
Submit code for review. Once the branch is synchronized, it may be submitted for review with git review
.
$ git review |
This submits the changes with the branch name as its topic.