Skip to content

Contributor Guidelines

Jump to bottom Edit New page
Eric Wittmann edited this page Aug 18, 2014 · 6 revisions

This page includes information to help guide developers when contributing to the Overlord projects.

Clone the Overlord git repo

First step is to fork the git repo, associated with the Overlord project you wish to work on, into your own github account. This can easily be achieved by going to the relevant project’s repo under the organization https://github.com/Governance, and selecting the Fork button at the top right of the page.

Once forked, you will need to create a local clone of your forked repo:

git@github.com:<username>/<overlord-project>.git

where <username> is the username of your github account, and <overlord-project> can be s-ramp, dtgov, rtgov, apiman, overlord-commons, or Governance.github.io (website).

Then establish an 'upstream' remote connection to the main repository:

git remote add upstream https://github.com/<username>/<overlord-project>.git

Select or create a JIRA to work on

Next step is to select the JIRA to be worked on. If one does not exist for the feature or bug you wish to work on, then please create one in the appropriate project’s JIRA. The project JIRAs are located here:

If planning to tackle a substantial feature, then it may be best to create (or convert the feature to) a task, and then create multiple sub-tasks to decompose the overall task into more manageable parts. This means that each task can be committed independently, and still tracked against the overall task for the feature. Note: it is not necessary to create all the sub-tasks upfront - sometimes it is better to just define the known sub-tasks and add further sub-tasks as they become relevant.

Create a branch for the JIRA

If you have just forked and cloned the Overlord git repo, then you can skip this next command. However if you have had the local repo for a while, then before creating a branch to work on the JIRA issue, you should ensure that the master branch is up to date. This can be done as follows:

git checkout master      // only required if you are not already on the master branch
git pull upstream master
git push origin master   // if the previous pull resulted in changes being applied

Now that we are sure the local repo’s master branch is up to date, we create the local branch for doing the work on the JIRA issue:

git checkout -b <branch-name>
Note
 The name of the branch should include the JIRA ticket (e.g. RTGOV-123). This makes it easier to correlate between the branch and the work being done.

Unit tests

Whenever possible, a unit test with adequate coverage must be included with the bugfix or new feature. This is absolutely vital and allows the projects to benefit from a wide range of regression tests. Most Overlord projects have a robust JUnit-based test architecture where new tests can be easily added. Please ping a core team member if you need any direction!

Verifying any changes

Once the work has been applied to the branch, please make sure that the project builds and the full test suite passes.

Note
 To avoid any checkstyle issues that may occur due to your changes, we have created an Eclipse formatter configuration that may help.

Please ensure that the comment is descriptive and starts with the JIRA code (e.g. "RTGOV-123 Added the feature to …​..").

Rebase the branch

Once the changes have been tested and committed to your branch, you will need to rebase your work against the latest master. This can be done in two ways, depending on whether multiple commits have been applied to your branch.

First you need to fetch the latest master from the upstream repo:

git fetch upstream

Single commit

If you only have a single commit in your branch, then:

git rebase upstream/master

Multiple commits

If you have more than one commit in your branch, then we prefer to only have a single commit with all of the changes associated with a particular JIRA issue. Therefore you will need to combine all of your commits into a single commit, using the following command:

git rebase -i upstream/master

This will cause a 'vi' editor window to be displayed containing the list of commits at the top of the file. Each line will start with word "pick". With the exception of the first line, all other lines should be changed to replace "pick" with the word "squash" instead.

Once this change has been made, save the file (:wq). This will cause another file to be opened in 'vi', containing the comments from all of the commits. Edit the file so that only a single comment remains that fully explains the changes that have been made - remembering to start the comment with the issue code (e.g. RTGOV-123).

Warning
 The change that has just been made has re-written the history associated with the branch. This should only be done in your own branches, where no other users have cloned that branch - otherwise it will cause those users problems.

Pushing the branch to github

The final step is to push the branch to the github repo:

git push -f origin <branchName>

The -f option is required if the previous rebase step has rewritten the branch’s history.

Issuing a Pull Request

Once the branch has been pushed to github, you should log in to your github account and navigate to your forked instance of the Overlord project.

Github will present a button, associated with the pushed branch, to enable you to compare it to the upstream master, and then issue a pull request.

Once the pull request has been issued, copy its URL and record it on the JIRA issue.

A member of the Overlord team will then review the pull request, test your changes against the latest upstream master, and either respond with comments - or if everything is fine, will apply the changes to the upstream master.

Add a custom footer
Add a custom sidebar
Clone this wiki locally