Documentation for PISM, a parallel Ice Sheet Model

Committing to PISM development

  1. Create an account on http://github.com.
  2. Set up Git on your own system, if it is not already present.
  3. Send an e-mail to help@pism-docs.org: we will add you to the “team” of PISM developers. We will make you a member of organization https://github.com/pism.
  4. Being a project member allows you to post "issues" at the github host, which may be labeled as “bugs”, “tasks”, “feature requests”, etc.
  5. Clone the PISM source code repository using Git, with a URL that includes write permission, and select the dev branch to work on:
     git clone -b dev git@github.com:pism/pism.git pism-dev 

Please commit all changes to the dev branch or “topical” branches. The stable branches, including the current default branch, are managed by PISM developers at UAF. Please feel free to fork the stable branches, however, especially if your changes are helped by having a non-changing base code.

To change the URL of the PISM repository in an existing clone, see man git-remote and look for the set-url command. This might be necessary if you cloned using a read-only URL.

Best practices

To satisfy our NASA-funded responsibility at UAF, we need to retain some little bit of control. We need PISM to do what we are funded to do. The following list of “best practices” facilitates such minimal control while encouraging healthy development. Perfection on these “rules” is not expected at any time. Mistakes are always forgiven. We are well-protected by version control.

  1. Non-UAF developers should commit on the dev branch and not on stable branches, because UAF manages stable releases. We do the merge of dev into the next stableX.Y release. If you find a bug in the stable release then please report it and we will fix it at UAF. Even better, send a pull request if you have fixed it in a fork, or send a patch to help@pism-docs.org. If a bug exists in dev and you can safely fix it directly, then that is much appreciated.
  2. The software tests present in the dev branch are somewhat-thorough regression tests. (They are better than nothing!) Please run them before a commit to minimally check that you have not broken something:
         cd 'your build directory'
         make install
         make test

    Proposing and building additional fast-running software tests for the dev branch is strongly encouraged.

  3. Posting a task (= an issue with a ''task'' label) describing what you plan to do is always reasonable before doing it. You can assign the task to yourself. Creating a git branch with a name like issue-XX is a good idea if you need to test before committing. If you are hoping a UAF developer will do something then you might mark it as a ''feature request'' instead of a task.
  4. Posting bugs (= an issue with a ''bug'' label) when you find them, including short runs that reveal the bug, is always worthwhile. This is true even if you already know how to fix the bug as other developers may see that related matters are affected. See also How to report a bug.
  5. When in doubt about adding spaghetti code because of existing/bad PISM design choices, please consider posting a task asking UAF developers for abstraction or modularization. You might be asking us to do something we want to do anyway, but it raises the priority.
  6. Please use a text editor aware of code indentation. Uses spaces, and not the “tab” character, to indent code.

Git workflow

The PISM team is currently using a simplified “merge” workflow and not a "pull request" workflow.

If you are just starting with Git, it may not be obvious how to use it to make changes and merge them into the dev branch at github.com/pism/pism. See the Git documentation page.

A reasonable principle is this: try to git pull only into a clean history. If not, you may find you are generating confusing modifications to the history seen by everyone.

Here is one suggested workflow if your first act was (already) to go change some source files in your working copy of dev branch:

YOU CHANGED FILES foo.cc bar.sh
git stash
git pull
git stash pop
RESOLVE ANY CONFLICTS
git add foo.cc bar.sh
git commit -m "why I changed stuff and how it makes it better"
git push

Note that git pull could be replaced by the two steps git fetch and git merge origin.

An alternative work flow with the same basic affect as the above is

YOU CHANGED FILES foo.cc bar.sh
git add foo.cc bar.sh
git commit -m "why I changed stuff and how it makes it better"
git status   # CHECK FOR OTHER UNCOMMITTED CHANGES (add, commit THEM IF PRESENT)
git pull --rebase
RESOLVE ANY CONFLICTS AND git add AND git commit FOR FILES WITH FIXED CONFLICTS
git push

Finally, a suggested alternative is to create a new 'topic' branch for your changes. Merge the changes in dev more-or-less frequently in to your new branch, and eventually merge your changes back into dev once you are done and the new 'topic' branch code has been tested.

committing.txt · Last modified: 2014/02/13 21:01 by Ed Bueler
© 2014 by PISM | webmaster