Guidelines for Extracting History

This post originally appeared on the Software Carpentry website.

As discussed previously, we are currently extracting individual lessons from the bc repository to make them more modular, which will ease use, contribution, and maintenance. This post presents some guidelines for extracting individual lessons and how to contribute to lessons in the meantime.

Individual lessons are currently in folders in the bc repository, e.g. novice/python. The aim of history extraction is to take the content and history of an individual lesson and move it to a new repository specifically for that lesson. We want to preserve history in order to recognise past contributions: just copying and pasting the files would lose this.

Using the novice Python lesson as an example:

1. One person takes ownership of the history extraction for a specific lesson and creates an issue in the bc repository with the labels Extract History, novice, Python and a title like "Extract history of novice Python lesson". Progress regarding the history extraction is then tracked in that issue (example). An overview of all of the current extractions can be seen using the Extract History label.

2. That person creates a personal repository, e.g. aaren/swc-novice-python where the history extraction takes place. The exact process used for extracting the history varies a little by lesson. Inspiration can be found in the Extract History issues, for example the novice python issue or the shell extraction. Briefly, that person needs to use git filter-branch to extract the history of the lesson, paying attention to path changes if the file was ever moved from one place to another, and extract the history of the cheat sheet stored in the novice/ref directory.

3. At this point the novice/python lesson in bc is frozen. All new issues and Pull Requests should be made against the new repository (linked in the issue).

4. When the history extraction is completed, the new issues and pull-requests can be reviewed. When all are dealt with, the lesson is frozen again and transitioned to fit the new lesson template.

5. Following the transition to the lesson template, the lesson is live and is in a permanent new home. That will probably be under the account for our core lessons, but could well be under someone else's account, for the same reason that people can host workshop websites under their own accounts if they choose: to support truly open collaboration.