Skip to content

Home

Jump to bottom
Graham Lopez edited this page Dec 14, 2016 · 27 revisions

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

  1. Fork A Repo (If you already have a fork, skip to Step 2.)

    This page describes how to

    1. create (fork) github:alice:qmcpack:* from the existing github:QMCPACK:qmcpack:* by clicking the "Fork" button in the top right corner on Github.
    2. create (clone) local:alice:qmcpack:* from the github:alice:qmcpack:* repo just created in "1.i."
    3. configure "upstream" to point to the original github:QMCPACK:qmcpack:*. This is needed for keeping the forked repo up-to-date with the original.

    This first step only needs to be done once. The same fork can be used for all subsequent new feature development activities.

  2. Sync new development from upstream (cf. Syncing a fork) (This is the starting point if the fork (Step 1) already exists. If you just forked, skip this step)

    1. Configuring a remote for a fork This makes github:QMCPACK:qmcpack:* "upstream" for the local repo local:alice:qmcpack:* (if not already done as in Step 1.iii)

    2. bring changes from github:qmcpack:qmcpack:develop into local:alice:qmcpack:develop

       $ git fetch upstream  (this will fetch changes from all branches  `github:qmcpack:qmcpack:*` but not merge them)
 $ git checkout develop
 $ git merge upstream/develop

    Now github:qmcpack:qmcpack:develop and local:alice:qmcpack:develop are in sync, but github:alice:qmcpack:develop will still need to be updated if desired. (Advanced: github:alice:qmcpack:develop doesn't really need to stay in sync, and in fact local:alice:qmcpack:develop could be set to track github:qmcpack:qmcpack:develop instead)

     $ git checkout develop
 $ git push

    Note that the Syncing a fork Github documentation describes the process for updating master. The $ git fetch upstream will get updates for all branches, so that this only needs to be done once to update multiple local branches from upstream (using $ git checkout <branch> ... $ git merge upstream/<branch>).

  3. Create a topic branch for the new feature

     $ git checkout -b <feature_branch>

    This is really a shortcut combination of the following two commands:

     $ git branch <feature_branch>
 $ git checkout <feature_branch>

  4. If some <feature_branch> has been around a while already, one can bring the new development into this working feature branch. Do this after performing Step 2 above.

     $ git checkout <feature_branch>
 $ git merge develop

  5. Make a branch available on Github for collaborating on the feature and for eventually submitting the pull request

     $ git push -u origin <feature_branch>

  6. Develop new feature, adding commits

  7. When the new feature is ready, it is time to think about Creating a pull request. (Read more [About pull requests] (https://help.github.com/articles/about-pull-requests/) here.)

    1. Sync local:alice:qmcpack:<feature_branch> with github:alice:qmcpack:<feature_branch>

       $ git checkout <feature_branch>
 $ git push

    2. Create a pull request from github:alice:qmcpack:<feature_branch> to github:QMCPACK:qmcpack:develop.

    To make suggested updates to the new feature code based on feedback from the testing or code reviews, just continue to make edits and commits in local:alice:qmcpack:<feature_branch>. When $ git push is used to update github:alice:qmcpack:<feature_branch>, the pull request will be automatically updated.

Create a private copy of the QMCPACK repository on Github.

TODO: explanation of when/why to use this

  1. Under the QMCPACK/ namespace on Github, click the new repository button.

  2. Pick a name (e.g. "newrepo"), and mark it as Public (this will change in step 6 below). Do not initialize with any README, .gitignore, license, or other files.

  3. On your local machine, clone the repository old repo (e.g. "oldrepo") to be forked and cd into its top directory.

     $ git clone https://github.com/qmcpack/oldrepo.git
 $ cd oldrepo

  4. "Mirror push" the old repo to the new repo that will become private

     $ git push --mirror https://[githubid]@github.com/qmcpack/newrepo.git

  5. Now you can delete the clone of the old repo on the local machine

     $ cd ..
 $ rm -rf oldrepo

  6. On the github website, go into the newrepo settings, and make it private

  7. Clone a working copy of the now private newrepo

     $ git clone https://[githubid]@github.com/qmcpack/newrepo.git

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

Clone this wiki locally