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:
One person takes ownership of the history extraction for a specific lesson and creates an issue in the
bc
repository with the labelsExtract 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.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 thenovice/ref
directory.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).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.
Following the transition to the lesson template, the lesson is live and is in a permanent new home. That will probably be under the {{site.github_url}} 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.