Version Control with Git: Customizing Your Workshop's Website

Configuration File _config.yml

You should edit the _config.yml configuration file in the root directory of your workshop to configure some site-wide variables and make the site function correctly:

For example, if the URL for the repository is https://github.com/gvwilson/2015-07-01-miskatonic, the URL for the website will be http://gvwilson.github.io/2015-07-01-miskatonic.

You should not need to modify any of the other values in _config.yml.

Home Page: Data

Your workshop’s home page lives in index.md, which must define the following values in its header:

The header may optionally define the following:

Home Page: Schedule and Syllabus

You should edit the sections titled Schedule and Syllabus so that they show what you’re actually planning to teach and when. These files are located in the appropriate workshop folder (dc, lc or swc) inside the _includes folder.

Home Page: Setup

You may have to edit the setup.html located in the dc, lc or swc folders inside the _includes folder that describes the software and data you will not be using in your workshop, so that learners don’t spend time installing software they don’t need.

Setup: Installation tests

If you intend to use the installation-test scripts, uncomment the paragraph linking to setup/index.html in index.md and edit setup/swc-installation-test-2.py as described below.

swc-installation-test-1.py is pretty simple, and just checks that the students have a recent enough version of Python installed that they can run swc-installation-test-2.py.

swc-installation-test-2.py checks for a list of dependencies and prints error messages if a package is not installed, or if the installed version is not current enough. By default, the script checks for pretty much anything that has ever been used at a Software Carpentry workshop, which is probably not what you want for your particular workshop.

Go through swc-installation-test-2.py and comment any dependencies you don’t need out of the CHECKS list. You might also want to skim through the minimum version numbers listed where particular dependencies are defined (e.g. ('git', 'Git', (1, 7, 0), None)). For the most part, fairly conservative values have been selected, so students with modern machines should be fine. If your workshop has stricter version requirements, feel free to bump them accordingly.

Similarly, the virtual dependencies can be satisfied by any of several packages. If you don’t want to support a particular package (e.g. if you have no Emacs experience and don’t want to be responsible for students who show up with Emacs as their only editor), you can comment out that particular or_dependency.

Updating the repository

If for some reason, such as the installation instructions having become disconnected with the current lesson material, you need to get changes from this repository into the clone of it with your workshop page, please follow the steps bellow:

  1. Add the workshop-template repository as upstream:

    $ git remote add upstream https://github.com/carpentries/workshop-template.git
    
  2. Fetch the data from upstream repository (also know as the workshop-template repository):

    $ git fetch upstream
    
  3. Merge the new changes:

    $ git merge upstream/gh-pages
    
  4. When get conflicts, solve it and

    $ git commit -a
    
  5. Push the changes to GitHub:

    $ git push origin gh-pages