diff --git a/_episodes/01-tooling.md b/_episodes/01-tooling.md index 0f63add227e340b0f77061b7f796241dd56994f4..58b8eb79860af3f8a0dad52a907d1d27c6b33648 100644 --- a/_episodes/01-tooling.md +++ b/_episodes/01-tooling.md @@ -15,35 +15,45 @@ keypoints: - "Each page's configuration is stored at the top of that page." - "Groups of files are stored in collection directories whose names begin with an underscore." --- -This episode describes tools we use to manage lessons, -which simplify many tasks but make other things more complicated. +This episode describes the tools we use to build and manage lessons. +These simplify many tasks, but make other things more complicated. ## Repositories on GitHub -All of our lessons are stored in Git repositories on GitHub. -Git uses the term *clone* to mean "a copy of a repository", -while GitHub uses the term *fork* to mean "a copy of a GitHub-hosted repo that is also hosted on GitHub" +Our lessons are stored in Git repositories (or "repos") on GitHub. +We use the term *fork* to mean "a copy of a GitHub-hosted repo that is also hosted on GitHub" and the term *clone* to mean "a copy of a GitHub-hosted repo that's located on someone else's machine". In both cases, the duplicate has a reference that points to the original repo. -A user on GitHub can only have one fork of a particular repo. -This is a problem for us because an author may be involved in writing several lessons, -each of which has its own website repo. -Those website repositories ought to be forks of the [template repository]({{ site.template_repo }}), -but since GitHub doesn't allow that, -we use [GitHub Importer][github-importer] when creating new lessons. +In an ideal world, +we would put all of the common files used by our lessons +(such as the CSS style files and the image files with project logos) +in a template repo. +The master copy of each lesson would be a fork of that repo, +and each author's working copy would be a fork of that master: + +![Forking Repositories]({{ site.root }}/fig/forking.svg) + +However, GitHub only allows a user to have one fork of any particular repo. +This creates a problem for us because an author may be involved in writing several lessons, +each with its own repo. +We therefore use [GitHub Importer][github-importer] to create new lessons. After the lesson has been created, we manually add the [template repository]({{ site.template_repo }}) as a remote called `template` to update the lesson when the template changes. +![Repository Links]({{ site.root }}/fig/repository-links.svg) + ## GitHub Pages If a repository has a branch called `gh-pages` (short for "GitHub Pages"), GitHub publishes its content to create a website for the repository. Websites can be static HTML pages, which are published as-is, -or can use [Jekyll][jekyll] as described below. +or can use [Jekyll][jekyll] as described below +to compile HTML and/or Markdown pages with embedded directives +to create the pages for display. If the repository's URL is `https://github.com/USERNAME/REPOSITORY`, the website is `https://USERNAME.github.io/REPOSITORY`. diff --git a/fig/forking.odg b/fig/forking.odg new file mode 100644 index 0000000000000000000000000000000000000000..d5d0067b1b62a56ff0df0fcc1f47ebff12e32070 Binary files /dev/null and b/fig/forking.odg differ diff --git a/fig/forking.svg b/fig/forking.svg new file mode 100644 index 0000000000000000000000000000000000000000..8d5298a33e37adcbc346b7077f4eb9bc25822c08 --- /dev/null +++ b/fig/forking.svg @@ -0,0 +1,211 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + template + + + + + + master copyof lesson A + + + + + + master copyof lesson B + + + + + + user X copyof lesson A + + + + + + user Y copyof lesson B + + + + + + user X copyof lesson A + + + + + + user Y copyof lesson B + + + + + + + + + + + + + + + + + + + + + + + + + + + + + swcarpentry + + + + + user X + + + + + user Y + + + + + + + + + + + + + + + + + Ideal Organization of Repositories(which we can't actually do) + + + + + + + \ No newline at end of file diff --git a/fig/repository-links.odg b/fig/repository-links.odg new file mode 100644 index 0000000000000000000000000000000000000000..5cff639221ed38328436eae3a1a05a415c407aae Binary files /dev/null and b/fig/repository-links.odg differ diff --git a/fig/repository-links.svg b/fig/repository-links.svg new file mode 100644 index 0000000000000000000000000000000000000000..851e516466637b8b2d47fc23cca7b1d7e2e1e2e0 --- /dev/null +++ b/fig/repository-links.svg @@ -0,0 +1,169 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + template + + + + + + master copyof lesson A + + + + + + user X copyof lesson A + + + + + + user X desktop copyof lesson A + + + + + swcarpentry + + + + + user X + + + + + + + + + + + + + + + + + upstream + + + + + template + + + + + origin + + + + + + + + + + + + + \ No newline at end of file