Documentation for PISM, the Parallel Ice Sheet Model

Committing to PISM development

  1. Create an account on
  2. Set up Git on your own system, if it is not already present.
  3. Send an e-mail to asking to be added to the “team” of PISM developers. We will make you a member of organization
  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 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 workflow is 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 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 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 or new-XX-model is a good idea if you need to test before committing. If you are hoping a UAF developer will do something to help you then you might mark it as a ''feature request'' instead of a task.
  4. Posting bug reports is always worthwhile! You can email to, but even better is to post a bug report at the github site (i.e. an issue with a ''bug'' label). See How to report a bug.
  5. Please post a bug report even if you already know how to fix it. That way other developers may see that related matters are affected.
  6. 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.
  7. 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 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:

git stash
git pull
git stash pop
git add
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

git add
git commit -m "why I changed stuff and how it makes it better"
git pull --rebase
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: 2017/02/22 06:03 by Ed Bueler
© 2020 by PISM | webmaster