Development Workflow

Main development

Fork glideinWMS/glideinwms repository

Create a fork of the main GitHub repo that you can work from (i.e. click on the fork button towards the upper right corner of this page). Then, clone that fork to your workspace:

$ git clone https://github.com/<my username>/glideinwms
$ 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/glideinWMS/glideinwms.git
$ git remote set-url --push upstream no_push
  # Pushes to main repo now disabled

If not already installed, install pre-commit, see the DEVELOPMENT document. Setup pre-commit for automated checks of your code by running this command from the repository root.

$ pre-commit install

You may want to set up 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 your copy with the main GitHub repo (glideinWMS/glideinwms). This can be done using pull requests in your fork on GitHub (merge glideinWMS/glideinwms into your fork) or locally from the command line:

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

You should be able to fast-forward because you are not expected to make changes to the main branch (master)

After any resyncing, rebase your branch off of master.

$ git rebase master <my branch>

When ready to commit, do so as needed:

$ git add ...
$ git commit ...

When writing a commit message consider:

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

Here is an example:

make default glidein_config robust to parallel updates

Made glidein_config more robust to parallel updates.
It will never be inconsistent but can still miss (not record) some updates done in parallel.
This is a transitional step, the next one, to make the process even more robust, will change the glidien_config format so it needs all the custom scripts to use the provided functions to save and retrieve attributes.

The documentation and the project changelog have been updated as well

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). Git should suggest you an URL to copy in your browser to open a PR. Open creating the PR (ensuring that the code is to be merged into the main glideinWMS/glideinwms repository), a review process will begin where fellow glideinwms developers will comment on your code and suggest whether it should be adjusted.

After a successful review, the code librarian will merge your PR into 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 to your local or forked main branch during a pull request: multiple commits in the PR may all get squashed into one single commit or rebased when the PR is merged. The next time you want to resync your main (master) branch, you might have to either

1. Use a pull request to merge glideinWMS/glideinwms 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>/glideinwms.git (fetch)
origin  https://github.com/<username>/glideinwms.git (push)
upstream        https://github.com/glideinWMS/glideinwms.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 the above procedure. Now we need to have an "old production" branch (e.g. vX.Y.Z) patched.

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

Fix conflicts if any. Then commit and push:

$ git push origin HEAD

Proceed to Web interface and create pull request against <branch>. origin is the name of your remote forked repository, assuming you have something like:

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

GitHub pull requests and different history resolution apply here as well.