All code commits to the master branch of the HPS Java project must go through a pull request procedure, so that changes are properly vetted by software experts within the collaboration.

Full Pull Request Procedure

Here is the full procedure for making a PR, including tips on how to structure your development workflow:

  1. Create a github issue describing the changes you plan on making to the code.

    You can add a new issue from this link:

    https://github.com/JeffersonLab/hps-java/issues/new

    You should assign the issue to yourself and tag it as an Enhancement if you are adding new functionality or a Bug if you are fixing an error.

    By default, you can set the Milestone to the next release tag (e.g. v4.1).

  2. Create a local development branch in your local copy of HPS Java.

    Start by updating the master so that your branch will be up to date when it is created.

    git checkout master; git pull


    Now create your local development branch based on the number in the issue tracker from step #1.

    cd hps-java; git checkout master; git pull; git checkout -b iss1234

    The "1234" should be replaced by the actual issue number assigned automatically by the issue tracker.  You can see this on the webpage for the issue you created.

  3. Add files to commit that you have changed or added on this branch.

    git add someNewFile aFileIChanged

    These file names are obviously bogus! (smile)

  4. Commit changes to added or modified files.

    git commit -m "I changed some stuff and this is my detailed commit message."

    These files are now "staged" which means that they will be sent to github next time you execute a push.

  5. Push your local branch to github.

    git push -u origin iss1234

    Unless you have your SSH keys setup properly, you will need to enter your github name and password.

    This command will create the remote branch "iss1234" branch which your local copy will now track, meaning that if someone else also pushes to this branch, like your PR reviewer or some other collaborator, then you may use a pull command to get these updates into your local copy.

  6. Now you should be ready to open a PR to get your changes merged into master.

    Start by going to this URL:

    https://github.com/JeffersonLab/hps-java/compare

    In the second dropdown box that says "compare: master", select your development branch (e.g. iss1234 in this example).

    Click the Create pull request button.

    Give the PR a valid description and provide some relevant information on what you changed.

    Select an appropriate reviewer by clicking on the gear icon next to Reviewers. 

    If you know the account name of the expert who should review your request, select them as the reviewer.  Otherwise assign to 'mholtrop' (software coordinator for HPS).

    Now click Create pull request again.

    The new PR should now be visible on github within the PR list.

    https://github.com/JeffersonLab/hps-java/pulls


  7. You now need to wait for your code to be reviewed and possibly tested depending on what was changed.

    The reviewer should provide feedback on changes they want to see before the request is merged, if there are any.

  8. Make changes requested by the reviewer using the typical 'git add', 'git commit' and 'git push' commands that were described above in steps 3-5.

  9. Once changes have been made to their satisfaction, the reviewer will approve the PR and your branch will be merged into the master.

    Now the master will have your changes so you can pull them into your local copy.

    git checkout master; git pull

  10. If the reviewer didn't do it for you when merging, you may also delete the local and remote branches if you are done with them.

    Delete the local branch:

    git branch -d iss1234

    Delete the remote branch:

    git push origin --delete iss1234

Resolving Problems

There are a few problems which may occur during the above procedure.

Most commonly the master may come into conflict with your branch if someone's changes to the same files are merged in before yours.

The most typical way to resolve this would be merging in the master to your branch by doing this:

git checkout iss1234; git merge master

Any files that are in conflict will be marked as such when you execute this command:

git status

In order to resolve these conflicts, you generally need to edit the files to get them into the state you want based on merging together the conflicting changes, typically by hand in your code editor.

Then you can use a standard git command to mark the conflicts as resolved:

git add thefileWithTheConflict

After this, commit and push the file in the normal fashion to the remote branch, which should resolve the conflict.

Another issue you might have is when your branch gets behind and you cannot push.  This is usually fixed by simple doing a "git pull" in order to get any remote changes into your branch so that it is up to date.

  • No labels