Home

Conventions used in this documentation

• To describe the location of branches, we use the abbreviation machine:gituser:repo:branchname. Obviously, this is not git command syntax. Here are some examples:
  • local:alice:qmcpack:newfeature (alice's "newfeature" branch in a "qmcpack" respository that is local to the repo cloned on her laptop/desktop, titan account home area, etc.)
  • github:bob:qmcpack:issue27 (the bob user's "issue27" branch that resides in his "qmcpack" repo on github)
  • github:QMCPACK:qmcpack:* (all branches in the "QMCPACK" organization's "qmcpack" repository on github)
• Commands typed at the linux comman prompt will be in fixed-width font and start with '$'. Command representation follows the conventions of the git man pages: Optional arguments are enclosed in square brackets. User-supplied information is enclosed in angle brackets. An example ("branch" is a user-supplied branch name argument that is optional):
  • $ git checkout [<branch>]
• PR, PRs = "pull request," "pull requests"

Project Development Policies

Develop a new feature and integrate it back into the main public repository

Create a private copy of the QMCPACK repository on Github

Using the 'git flow' git extensions TODO

see https://github.com/nvie/gitflow

Helpful configuration for developers TODO

• .gitconfig settings
  • name and email address for commits
  • helpful aliases
• skip typing github username
• skip typing github password

Developers handling pull request code reviews TODO

• code review checklist

Maintainers handling pull request submissions and merging TODO

Merging a pull request

outline

• PR comes in for 'develop'
• CI and github checks
  • if CI fails or not a clean merge, maintainer asks submitter to fix
• maintainer does sanity checks
  • patch is logically sized (one main 'topic' for the patch, hopefully < 1k lines)
  • code formatting
  • well commented/documented
• Submitter addresses comments from maintainer(s)
• If required, maintainer tags project developer(s) to review and comment
• Submitter addresses comments from developer(s)
• Once developers and maintainers give '+1', thumbsup, okay, whatever, maintainer merges PR into 'develop'

Transition todo

• Documentation — github wiki and/or qmcpack manual
  • general developer workflows (graham)
  • pull request handling for maintainers (graham)
  • code review checklist (graham)
  • release process
  • old wiki move - what to include?
  • issue processes - how to assign and close? e.g. issue fixer should not close, to force a doublecheck
• CI
  • infrastructure availability status (graham)
  • how to automate code formatting check/enforcing (graham)
    • based on style at https://sites.google.com/a/cmscc.org/qmcpack/developers-forum/coding-guides
    • checkout:
      • http://stackoverflow.com/questions/22866609/can-clang-format-tell-me-if-formatting-changes-are-necessary
      • http://www.labri.fr/perso/fleury/posts/programming/using-clang-tidy-and-clang-format.html
      • https://llvm.org/svn/llvm-project/cfe/trunk/tools/clang-format/git-clang-format
  • update scripts for new CI infrastructure
  • remove svn specifics from testing infrastructure and code
  • partition tests into PR, nightly, weekly
  • how to deal with nightly/weakly failures/regressions? - maintainer triages and assigns to right person?
• SVN to git repo conversion
  • authors file / translation svn to github emails - "best effort" (mark)
  • archive old issues (mark)
  • move open issues (mark)
    • how to deal with comment chains? cut/paste into main body of corresponding issue on github. use github API?