-
Notifications
You must be signed in to change notification settings - Fork 139
Home
- To describe the location of branches, we use the abbreviation
machine:gituser:branchname
. Obviously, this is not git command syntax. Here are some examples:-
local:alice:newfeature
(alice's "newfeature" branch that is local to the repo cloned on her laptop/desktop, titan account home area, etc.) -
github:bob:issue27
(the bob user's "issue27" branch that resides on github) -
github:qmcpack:*
(all branches in the 'qmcpack' organization's 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"
- Under the fork and pull request model that QMCPACK uses,
origin
will refer to the user's own forked repository hosted on Github (e.g.github:alice:*
), andupstream
will refer to the public QMCPACK repository (i.e.github:qmcpack:*
).
See the Github documentation about forking a repository. This page describes how to fork a repository, and then how to keep that fork in sync with the original repository.
See the Github documentation about pull requests.
This downloads the repository somewhere that actual changes can take place. If changes will be made and submitted back to the main code base, this should always be done from a user's forked repository and never from the QMCPACK public repository because PRs should be submitted from the developer's own user account.
$ git clone https://[<github id>]@github.com/qmcpack/qmcpack.git
TODO
TODO: explanation of when/why to use this
-
Under the QMCPACK/ namespace on Github, click the new repository button.
-
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.
-
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
-
"Mirror push" the old repo to the new repo that will become private
$ git push --mirror https://[githubid]@github.com/qmcpack/newrepo.git
-
Now you can delete the clone of the old repo on the local machine
$ cd .. $ rm -rf oldrepo
-
On the github website, go into the newrepo settings, and make it private
-
Clone a working copy of the now private newrepo
$ git clone https://[githubid]@github.com/qmcpack/newrepo.git
User 'bob' wants to develop a new feature and integrate it into the main code base.
-
First, bob makes sure that his local repo's
develop
branch is up-to-date: (see https://help.github.com/articles/syncing-a-fork/)$ git checkout develop $ git pull upstream/develop
-
Next, bob creates a new branch from
local:bob:develop
for his new feature development.$ git branch <newfeature>
-
Bob makes his branch available on Github for collaborating on the feature, and also for submitting the pull request
$ git push origin <newfeature>
-
(Optional) Bob invites other developers to collaborate on this feature with him. Alice can start collaborating with Bob by pulling his new branch:
$ FIXME
-
Development ensues (edit files, commit changes, repeat until finished)
-
Once bob wants to submit the code back to the main project, he opens a pull request:
TODO: see https://github.com/nvie/gitflow
-
.gitconfig
settings- name and email address for commits
- helpful aliases
- skip typing github username
- skip typing github password
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'
- 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:
- 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?