CMS Open Data Workshop 2022

This is the main repository for the CMS Open Data Workshop 2022 event. The workshop is based on The Carpentries' (Software Carpentry, Data Carpentry, and Library Carpentry's) templates for creating websites for workshops. In particular, we followed the instructions in the official workshop template repository and used the "template" function to make a copy and customize it. As it is explained there, it builds automatically on Github.

How to contribute

In order to modify the main workshop website, i.e., this repository, please follow the SW Carpentry's default instructions.

Lessons are generally added to the main workshop site from a repository in the current Github organization called styles, i.e., from the cms-opendata-workshop organization. If you need to create or modify a lesson, please follow the instructions below. It is important to use the local styles repository as it is tailored to CMS needs.

Creating a lesson

In order to create a new lesson for this workshop, follow the procedure below (which is based on these original instructions, but with details concerning this workshop):

We will assume that the name of your the new lesson is worshop2022-lesson-temp (make sure you name it properly, replacing lesson-temp with the appropriate name for your lesson.)

1. We'll use the GitHub's importer to make a copy of the lesson template in the workshops github organization. (Note: This is like a GitHub Fork, but not connected to the upstream changes)

2. Put the URL of the styles repository, that is https://github.com/cms-opendata-workshop/styles, in the "Your old repository’s clone URL" box. Make sure you do not use the carpentries style repository as this one will not be tailored with CMS logos, etc.

3. Select the owner for the new repository as cms-opendata-workshop.

4. Choose a name for your lesson repository. In our example, this is worshop2022-lesson-temp. Please follow this pattern, i.e., workshop2022-lesson-{description}

5. Make sure the repository is public.

6. At this point, you should have a page like this:

   

   You can now click "Begin Import". When the process is done, you can click "Continue to repository" to visit your newly-created repository.

7. In order to properly initialize the lesson repository, you need to work from your local machine or have someone do it for you (after the initialization process is done, you can work directly using the Github browser page). Clone your newly-created repository to your computer:

   $ git clone -b gh-pages https://github.com/cms-opendata-workshop/workshop2022-lesson-temp.git
   

   Note: Replace the name of your lesson.

8. Go into that directory using:

   $ cd workshop2022-lesson-temp
   

9. To be able to pull upstream style changes, you should manually add the styles repository as a remote called template:

   $ git remote add template https://github.com/cms-opendata-workshop/styles.git
   

   This will allow you to pull in changes made to the template, such as improvements to our CSS style files.

10. Configure the template remote to not download tags:

    $ git config --local remote.template.tagOpt --no-tags
    

11. Make sure you are using the gh-pages branch of the lesson template:

    $ git checkout gh-pages
    

12. Run bin/lesson_initialize.py to create all of the boilerplate files that cannot be put into the styles repository (because they would trigger repeated merge conflicts).

13. Create and edit files as explained further in the episodes of this lesson.

14. (requires Jekyll Setup from below) If working locally, preview the HTML pages for your lesson:

    $ make serve
    

    Alternatively, you can try using Docker:

    $ make docker-serve
    

15. Commit your changes and push to the gh-pages branch of your repository:

    $ cd workshop2022-lesson-temp
    $ git add changed-file.md
    $ git commit -m "Explanatory message"
    $ git push origin gh-pages
    

16. Do not forget to choose the gh-pages branch as the default one: go to the Settings option of the new lesson repository, chosee Branches from the left menu, and choose the gh-pages branch as the default.

17. Finally, in order to facilitate the access to the live site, go to the Settings page of the lesson repository, then to the Pages option on the left menu, and copy the live web link to the About description of the main page of you lesson repository.

Working locally

There is the option of working directly on Github using your web browser. However, whether you are working on the main site or on a particular lesson, it is always recommended to work locally, so you can test the looks of the material before you push your changes to the repositories.

If you are already familiar with Git, you can clone the repository to your local machine, edit anything you need and push your changes back to the repository.

git clone https://github.com/your_username/YYYY-MM-DD-site

In order to view your changes once you are done editing, if you have bundler installed (see the installation instructions below), you can preview your site locally with:

make serve

and point your browser to http://127.0.0.0:4000 (or to whatever address the execution of the last command points you to) to preview your site.

Before pushing your changes to your repository, we recommend that you also check for any potential issues with your site by running:

make workshop-check

Once you are satisfied with the edits to your site, commit and push the changes to your repository. A few minutes later, you can go to the GitHub Pages URL for your workshop site and preview it.

Note: please do all of your work in your repository's gh-pages branch, since GitHub automatically publishes that as a website.

Note: this template includes some files and directories that most workshops do not need, but which provide a standard place to put extra content if desired. See the design notes for more information about these.

Further instructions are available in the customization instructions. This FAQ includes a few extra tips (additions are always welcome) and these notes on the background and design of this template may help as well.

Installing Software

If you want to set up Jekyll so that you can preview changes on your own machine before pushing them to GitHub, you must install the software described in the lesson example setup instructions.

Note: There might be some issues with the ruby versions. The default Carpentry instructions may be outdated. One might need to fiddle a little bit with the installation. Fortunately, there are external (Google) instructions that can be used to fix potential problems.

Getting and Giving Help

Please join our Mattermost channel or contact us.