-
Notifications
You must be signed in to change notification settings - Fork 8
Workflow
There is a central repository for all boot camp
material. The master branch has the current state-of-the-art source
for the instructors' projected content, handouts, boot camp homepage,
…. If we can't agree on a canonical representation, there may be a
handful of feature branches with alternative content.
NOTE: SWC has not yet formed a consensus about the structure of the
master branch.
Topics will live in per-subject subdirectories, ideally organized in half-day-sized chunks.
.
├── README.md
├── debugging
│ ├── README.md
│ …
├── make
│ ├── README.md
│ ├── example-project
│ …
├── python
│ ├── README.md
│ ├── animals.txt
│ …
├── shell
│ …
├── version-control
│ ├── git
│ │ ├── basic
│ │ │ …
│ │ └── advanced
… … …
Figure 1: Example directory tree for the current master tip.
Sections should be in half-day-ish chunks. Complicated topics
that need more detailed coverage (e.g. version control) can have
nested sub-sections.
If you haven't worked on any boot camp content before, you'll need to clone the master repository. You'll also want a way to publish your changes. Because GitHub pull requests require the pulled head to be on GitHub, that means you'll need a GitHub account. Log into GitHub, and fork the boot-camps repository. Clone your fork with:
$ git clone https://github.com/YOU/boot-camps.git
$ cd boot-camps
You'll want to track the SWC repository to stay abreast of changes, so add it as a remote and fetch it:
$ git remote add swc https://github.com/swcarpentry/boot-camps.git
$ git fetch swc
Now you're ready to start hacking away.
An instructor preparing for a new boot camp should create a per-camp
branch from the upstream master:
$ git checkout -b 2012-12-my-camp swc/master
and optionally merge feature branches they like:
$ git merge swc/git-wtk
This gives a starting point for developing your boot camp.
-o---o---o---o swc/master (same as local master)
\ \
o---o \ swc/git-wtk
\ \
`-------M 2012-12-my-camp
Figure 2: Graph of commits for the beginning of the
2012-12-my-camp branch. Time increases to the right. Commits are
marked with “o”. ASCII art connects child commits with their
parents. The merge of a well-maintained feature branch (marked
with an “M”) should be painless.
If you don't have strong ideas about the content, there's probably not much to do here besides tweaking a few boot-camp-specific bits (location, dates, master-index, …). These changes should go into the boot camp branch:
$ emacs README.md
(edit linking)
$ git commit -am 'README.md: link to shell, git/basic, and git/advanced'
$ emacs README.md
(localize for your boot camp)
$ git commit -am 'README.md: localize for 2012-12 boot camp at my house'
This creates:
-o---o---o---o swc/master (same as local master)
\ \
o---o \ swc/git-wtk
\ \
`-------o---A---B 2012-12-my-camp
Figure 3: Boot-camp-specific changes go into the boot-camp-specific
branch. Example log:
commit message
------ -----------------------------------------------------
A README.md: link to shell, git/basic, and git/advanced
B README.md: localize for 2012-12 boot camp at my house
If you want to change some of the general content, you should make your change on the master branch (or the feature branch like “git-wtk”).
$ git checkout -b typo-fix swc/master
$ sed -i 's|origin\\master|origin/master|g' version-control/git/basic/README.md
$ git commit -am 'git/basic: fix origin\master -> origin/master typo'
Publish your feature branch in your GitHub repository:
$ git push origin typo-fix
And make a pull request on GitHub to get your feature branch merged upstream.
While the feature branch is being discussed upstream, go ahead and merge your changes into your boot camp branch.
$ git checkout 2012-12-my-camp
$ git merge typo-fix
This creates:
A-------------. typo-fix
/ \ \
-o---o---o---o-----------\-----C swc/master
\ \ \
o---o \ \ swc/git-wtk
\ \ \
`-------o---o---o---B 2012-12-my-camp
Figure 4: You can't push to master, so you made a new “typo-fix”
branch. Later on, a SWC dev will merge it into master. Example
log:
commit message
------ --------------------------------------------------
A git/basic: fix origin\master -> origin/master typo
B merge recent master branch updates
C git/basic: merge origin\master typo fix
After your feature branch has been merged into your boot camp branch and the upstream branch, it no longer needs a convenient name. Delete the branch itself:
$ git branch -d typo-fix
You'll also want to remove the branch from your public GitHub repository:
$ git push origin :typo-fix
The boot camp branch is a clean record of how your source developed and the particular material that you presented to your students. You should publish your final branch state on your GitHub repository:
$ git push origin 2012-12-my-camp
and submit a pull request (the base branch should match your
YYYY-MM-LOCATION branch tag). The base branch of your pull request
is irrelevant; GitHub doesn't allow you to explicitly request new
branches with pull requests.
After the pull request is accepted (which shouldn't take long, since there shouldn't be any controversy over its content), the developer who merged the pull request will tag the boot camp branch and delete the branch itself
$ git tag 2012-12-my-camp swc/2012-12-my-camp
$ git push swc tag 2012-12-my-camp
$ git push swc :heads/2012-12-my-camp
Git branches are basically tags that move. Once the boot camp is done, there's no need for its tip commit to change, so you might as well mark it with a tag. After your branch has been tagged upstream, you can fetch the new tag with:
$ git fetch swc
The new tag should match your branch tip, so you can safely delete the branch:
$ git branch -d 2012-12-my-camp
Then push any new tags to your public GitHub repository and remove the old branch.
$ git push --tags origin
$ git push origin :heads/2012-12-my-camp
The following notes provide helpful hints for managing your repositories. Feel free to skip them if they don't sound interesting.
If you don't like remote branches cluttering your local repo, you can clone a single branch of the master repository using:
$ git clone --single-branch https://github.com/YOU/boot-camps.git
You can also limit the branches you fetch from upstream. After adding
the swc remote, run:
$ git config remote.swc.fetch +refs/heads/master:refs/remotes/swc/master
After this, future calls to git fetch will retrieve only the
master branch from swc and its associated tags, ignoring other
branches and unrelated tags.
If you really want to roll your own content, feel free to skip the master branch entirely.
-o---o---o---o swc/master
\
o---o swc/git-wtk
I---o---o---o 2012-12-my-camp
Figure 5: A disjoint branch (2012-12-my-camp). The commit “I”
has no parents. Different branches stored in the same repository
don't need to share any common commits. They're still addressing
the same goal, and having them in the same repo means its easier to
clone/fetch/diff/….
If you don't like forking and issusing pull requests from the GitHub
websites, you can use hub to perform these operations from the
command line. Hub is available as dev-vcs/hub in Evgeny Mandrikov's
godin overlay on Gentoo; installation instructions for some
other platforms is available in the README.
Using hub to submit pull requests is similar to using Git's builtin
request-pull command, except that hub created pull requests on
GitHub, while request-pull prints a message onto stdout that should
be emailed to the maintainer.
$ git clone https://github.com/swcarpentry/boot-camps.git
$ cd boot-camps
$ hub fork
This is the same as the hub-less procedure, except that the remote names have changed.
hub-less hub Repository URL
======== ====== ===========================================
swc origin git://github.com/swcarpentry/boot-camps.git
origin YOU git://github.com/YOU/boot-camps.git
You'll have to make appropriate adjustments to the other commands
(e.g. for creating a new boot camp, branch off from origin/master
instead of swc/master).
Create your feature branch as described for hub-less development, but
after publishing to YOU/feature-branch you can create the pull
request using hub:
$ hub pull-request
The pull request base defaults to the tracked branch and the head defaults to the current branch, so you shouldn't need to specify either explicitly.
After publishing your boot camp branch to YOU/2012-12-my-camp,
create a pull request using:
$ hub pull-request 'tag completed 2012-12-my-camp' -b origin:master
As mentioned earlier, don't worry about having master as the base
branch.