-
-
Notifications
You must be signed in to change notification settings - Fork 265
Workflow
This page tries to explain each of the steps, if you want to cut out the chatter, see the condensed version.
- An overview of the repository structure
- Cloning the master repository
- Creating a new boot camp branch
- Publishing your local work in a branch of a GitHub repository
- Developing boot camp content
- Post-boot-camp archival
- Tweaks and hints
The important parts to get right before your boot camp are cloning, branch creation, publishing, and development. This clone/branch/develop/publish/(merge) cycle is the common Git workflow, so there are lots of tutorials to get you oriented, if the information here is not sufficient. Also feel free to ask on the mailing list or IRC.
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 use branches on the master repository to publish your changes. Clone with:
$ git clone https://github.com/swcarpentry/boot-camps.git
$ cd boot-camps
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 origin/master
and optionally merge feature branches they like:
$ git merge origin/git-wtk
This gives a starting point for developing your boot camp.
-o---o---o---o origin/master (same as local master)
\ \
o---o \ origin/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.
The checkout -b command mentioned above creates a new branch in your
local repository, but you'll want to publish this branch so others can
see it. Push your branch to the public repository with:
$ git push origin 2012-12-my-camp
GitHub doesn't accept pushes via the git:// protocol, so you'll want
to use an https:// URL (with optional password caching) or
setup SSH keys and push over SSH. You can list remotes and
their associated URLs with git remote -v to help you remember what
you've already configured.
You'll want to push again whenever you need to publish additional local work.
If you don't have push access to the swcarpentry repository, just ask an admin to set you up.
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 origin/master (same as local master)
\ \
o---o \ origin/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 in a feature branch based on the master branch (or based
on a general feature branch like git-wtk). Pick a unique name for
your branch to avoid colliding with existing branches.
$ git checkout -b typo-fix origin/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 origin/master
\ \ \
o---o \ \ origin/git-wtk
\ \ \
`-------o---o---o---B 2012-12-my-camp
Figure 4: Pushing directly to master is bad form, 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 the 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 push your final branch state to the 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.
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 origin/2012-12-my-camp
$ git push origin tag 2012-12-my-camp
$ git push origin :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 origin
The new tag should match your branch tip, so you can safely delete the branch:
$ git branch -d 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/swcarpentry/boot-camps.git
You can also limit the branches you fetch from upstream. For example:
$ git config remote.origin.fetch +refs/heads/master:refs/remotes/origin/master
will setup future calls to git fetch to retrieve only the master
branch from origin 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 origin/master
\
o---o origin/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.
$ hub clone swcarpentry/boot-camps
$ cd boot-camps
Create your feature branch as described for hub-less development, but
after publishing to 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 if you previously pushed with -u:
$ git push -u origin feature-branch
After publishing your boot camp branch to 2012-12-my-camp,
create a pull request using:
$ hub pull-request 'tag completed 2012-12-my-camp' -b origin:master
Don't worry about having master as the base branch, we're just using
the pull request as a way to record which branch you'd like tagged.