Development Workflow

Normal development workflow

Fork HEPCloud/decisionengine repository

Create a fork of the main github repo that you can work from. Then, clone that fork to your workspace:

$ git clone https://github.com/<my username>/decisionengine
$ git pull
$ git checkout -b <my branch>

Provide the upstream remote repository, which is helpful in keeping your fork synchronized with the main GitHub repo:

$ git remote add upstream https://github.com/HEPCloud/decisionengine.git
$ git remote set-url --push upstream no_push
  # Pushes to main repo now disabled

Setup pre-commit for automated checks of your code by running this command from the repository root.

$ pre-commit install

You may want to setup automatic notifications for pre-commit enabled repos: https://pre-commit.com/index.html#automatically-enabling-pre-commit-on-repositories

And you can run manually pre-commit on all files:

$ pre-commit run --all-files

Develop on your branch

Remember to periodically sync the main github repo (HEPCloud/decisionengine) with your copy of the repo. This can be done using pull requests in your fork on github (merge HEPCloud/decisionengine into your fork) or locally from the command line:

$ git fetch upstream master
$ git checkout master
$ git merge upstream/master

After any resyncing, rebase your branch off of master.

$ git rebase master <my branch>

When ready to commit, do

$ git commit ...

When writing commit message consider:

1. Removing all intermediate commit messages you might have made while developing your patch
2. Use concise statement to summarize patch.
3. Write details in the next line

Here is an example:

decisionengine/logicengine: python3 compliance changes 

Replaced string.join() where appropriate 

Then push to the remote:

$ git push origin <my branch> 

GitHub pull requests and reviews

Once your commit has been pushed to your GitHub fork, you will be able to open a pull request(PR). Open creating the PR (ensuring that the code is to be merged into the main HEPCloud/decisionengine repository), a review process will begin where fellow decisionengine developers will comment on your code and whether it should be adjusted.

After a successful review, the code librarian will merge your PR with the main GitHub repository.

Resolving different git histories

After your PR is merged, you may find that your forked repository shows a different commit history than the upstream repo. This can especially happen if you made any commits during a pull request: these all get squashed into one commit automatically when the PR is merged. The next time you want to resync your master branch, you might have to either

1. Use a pull request to merge HEPCloud/decisionengine into your local repo, or
2. Force a resync of your forked copy of the repository with the main repo. Assuming your git remotes are set like this:

$ git remote -v
origin  https://github.com/<username>/decisionengine.git (fetch)
origin  https://github.com/<username>/decisionengine.git (push)
upstream        https://github.com/HEPCloud/decisionengine.git (fetch)
upstream        no_push (push)

you could do the following:

$ git fetch upstream
$ git checkout upstream/master
$ git branch -D master
$ git checkout -b master
$ git push --force origin master

Bug fixes to frozen branch

Assumption is: you have fixed the bug and pushed it to master using above procedure. Now we need to have a "production" branch patched.

$ git checkout <branch>
$ git pull <branch>
$ git checkout -b fix/<branch>/<optional>
$ git cherry-pick -x <HASH of the bugfix commit to master>

Fix conflicts if any

$ git push <remote> HEAD

Proceed to Web interface and create pull request against <branch>. <remote> is the name of your remote repository. For instance:

$ git remote -v 
litvinse	[email protected]:DmitryLitvintsev/decisionengine.git (fetch)
litvinse	[email protected]:DmitryLitvintsev/decisionengine.git (push)
origin	https://github.com/HEPCloud/decisionengine (fetch)
origin	https://github.com/HEPCloud/decisionengine (push)

The name of remote repository is litvinse.