X-Git-Url: http://git.tremily.us/?p=workshop-organization.git;a=blobdiff_plain;f=branch;h=2ccba623c8292055d3623393fcff92590ab32c83;hp=67697b0739e493e21c25d48d937bd5de0d21f120;hb=HEAD;hpb=9fc58a9d449c8d7955c34bd342b649115496ff74 diff --git a/branch b/branch index 67697b0..2ccba62 100644 --- a/branch +++ b/branch @@ -5,53 +5,25 @@ There is a central repository for all boot camp material [1]. https://github.com/swcarpentry/workshop -The “master” branch has the current state-of-the-art source (Markdown, -ReST, LaTeX, …) for the instructors' projected content (HTML pages, -PDF slides, …), handouts, workshop homepage, …. If we can't agree on -a canonical representation, there may be a handful of feature branches -with alternative content. - -An instructor preparing for a new workshop should create a -per-workshop branch from the master: - - $ git checkout -b 2012-12-my-workshop master - -and optionally merge feature branches they like: - - $ git merge git-wtk - -This gives a starting point for developing your workshop. - - -o--o--o--o--o master - \-o--o \ git-wtk - \------o 2012-12-my-workshop - - Figure 1: Graph of commits for the beginning of the - 2012-12-my-workshop 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 should be - painless. - -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 … +The “master” branch has the current state-of-the-art source for the +instructors' projected content, handouts, workshop homepage, …. If we +can't agree on a canonical representation, there may be a handful of +feature branches with alternative content. Topics will live in per-subject subdirectories, ideally organized in half-day-sized chunks. . - ├── README - ├── index.rst + ├── README.md ├── debugging - │ ├── index.ipynb + │ ├── README.md │ … ├── make - │ ├── index.md + │ ├── README.md │ ├── example-project │ … ├── python - │ ├── index.rst + │ ├── README.md │ ├── animals.txt │ … ├── shell @@ -59,15 +31,41 @@ half-day-sized chunks. ├── version-control │ ├── git │ │ ├── basic - │ │ │ … + │ │ │ … │ │ └── advanced … … … - Figure 2: Example directory tree for the current 2012-12-my-workshop + Figure 1: Example directory tree for the current 2012-12-my-workshop 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. +An instructor preparing for a new workshop should create a +per-workshop branch from the master: + + $ git checkout -b 2012-12-my-workshop master + +and optionally merge feature branches they like: + + $ git merge git-wtk + +This gives a starting point for developing your workshop. + + -o--o--o--o--o origin/master (same as local master) + \-o--o \ origin/git-wtk + \------o 2012-12-my-workshop + + Figure 2: Graph of commits for the beginning of the + 2012-12-my-workshop 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 should be + painless. + +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 … + Developing workshop content =========================== @@ -76,8 +74,8 @@ much to do here besides tweaking a few workshop-specific bits (location, dates, master-index, …). These changes should go into the workshop branch: - -o--o--o--o--o master - \-o--o \ git-wtk + -o--o--o--o--o origin/master + \-o--o \ origin/git-wtk \------o--a--b 2012-12-my-workshop Figure 2: Workshop-specific changes go into the workshop-specific @@ -85,73 +83,48 @@ workshop branch: commit message ------ ----------------------------------------------------- - a index.rst: link to shell, git/basic, and git/advanced - b index.rst: localize for 2012-12 workshop at my house - -If you want to change some of the general content, you have some -choices. - -1. With commit rights to the central repo, go ahead and make your - change on the master branch (or the feature branch like “git-wtk”). - Then pull your changes into your workshop branch. - - -o--o--o--o--o--a-----\ master - \-o--o \ \ git-wtk - \------o--o--o--b 2012-12-my-workshop - - Figure 3: General changes go into their general branch. Example log: - - commit message - ------ -------------------------------------------------- - a git/basic: fix origin\master -> origin/master typo - b merge recent master branch updates - -2. If you can't commit to the central repo, put your changes in their - own feature branch and make a pull request. - - /-a----\---\ typo-fix - -o--o--o--o--o--------\---c master - \-o--o \ \ git-wtk - \------o--o--o--b 2012-12-my-workshop - - 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 (c). The - content of commits “a” and “b” is the same as in Figure 3. - -3. You don't like this fancy branch stuff, so you just make the commit - in your workshop branch. You let the SWC devs know so they can - cherry-pick it into the master branch. - - -o--o--o--o--o------------d master - \-o--o \ : git-wtk - \------o--o--o--a 2012-12-my-workshop - - Figure 5: You make the general change “a” in your workshop branch. - SWC devs have to cherry pick the change into the master with “d”. - This makes it awkward for other people to base work off your - workshop branch. It is even more awkward if you've stuffed - workshop-specific changes into “a”, but you can avoid that by - making clean commits. - -4. If you really want to roll your own content, feel free to skip the - master branch entirely. - - -o--o--o--o--o master - \-o--o git-wtk - I--o--o--a 2012-12-my-workshop - - Figure 6: A disjoint branch (2012-12-my-workshop). 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/…. + a README.md: link to shell, git/basic, and git/advanced + b README.md: localize for 2012-12 workshop 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”). Then pull your changes into your workshop branch and make +a pull request for inclusion in the master repository. + + /-a----\---\ typo-fix + -o--o--o--o--o--------\---c origin/master + \-o--o \ \ origin/git-wtk + \------o--o--o--b 2012-12-my-workshop + + Figure 3: 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 + +If you really want to roll your own content, feel free to skip the +master branch entirely. + + -o--o--o--o--o origin/master + \-o--o origin/git-wtk + I--o--o--a 2012-12-my-workshop + + Figure 4: A disjoint branch (2012-12-my-workshop). 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/…. Publishing workshop websites ============================ This is not really part of the workshop-branch vs. workshop-repo discussion, but one benefit to the workshop-repo approach is that each -workshop has a gh-pages website at +workshop may have a gh-pages website at http://.github.com/ http://swcarpentry.github.com/2012-12-my-workshop @@ -178,8 +151,8 @@ need for its tip commit to change, so you might as well mark it with a tag. If your workshop branch has been living in your own personal -repository. Submit a pull request to the master repo, and a SWC dev -will import your branch, tag the tip, and delete the branch for you. +repositor, submit a pull request to the master repo. A SWC dev will +import your branch, tag the tip, and delete the branch for you. [1]: There's a mock-up at https://github.com/wking/swc-workshop