search

carpentries / workbench

Repository for Discussions and Materials about The Carpentries Workbench
https://carpentries.github.io/workbench/
Creative Commons Attribution 4.0 International
17 stars 7 forks source link

What the easiest way to update a long-running fork to use the new workbench? #51

Open gcapes opened 1 year ago

gcapes commented 1 year ago

Let's say I have a long-running fork of a carpentries lesson I want to update to use the new style (@cjfullerton). Or (actually me) I have a lesson which uses the previous carpentries lesson template - what is the least painful way to transition this to use the new workbench format?

The FAQ indicates the easiest way to 'update' your fork is to re-fork, but doesn't offer any other suggestions.

If I decide to use the new format for my lesson and it's not loads of hassle I would like to keep my git history rather than starting again and moving the markdown content into the new template, and updating all the callout etc syntax.

I guess the lack of any further suggestions probably answers the question, but if the answer is simply "it's loads of hassle, just start again" that's ok, and good to have confirmed :)

tobyhodges commented 1 year ago

I don't think it's reflected in the sandpaper-docs documentation yet, but @zkamvar has been very thorough in documenting the tools he used to manage the transitions of official lessons over in the carpentries/lesson-transitions repository: https://github.com/carpentries/lesson-transition#transitioning-carpentries-lessons

That documentation is pretty comprehensive, but I think the process itself is not to be taken lightly. Perhaps you'd like to give it a go and report back? We have been discussing scheduling onboarding sessions for this process, e.g. to help folks working on lessons in the Incubator, and any constructive feedback you can provide on the process and the documentation could be very helpful in making sure those are impactful.

zkamvar commented 1 year ago

Hi @gcapes,

The easiest way is to convert your fork to use the new format locally, make a new fork, and push one big commit with your changes.

If I decide to use the new format for my lesson and it's not loads of hassle I would like to keep my git history

It is also possible do do this without losing any of the git history (including the styles commits), by making a copy of the repository, renaming _episodes to episodes and then running the transform-lesson.R script (as shown in the filter-and-transform.sh script.

Note

Syntax transformation is done automatically from the transform() function for episodes and the rewrite() function for auxilary markdown files.

You'll have to do some clean up of the other Jekyll folders, but the transformation script takes care of most of the heavy lifting, but again, you will not be able to contribute to or bring in changes from the upstream repo.

You could also just do a full transition, which will keep your content-specific changes and discard the styles changes, but merging will be a hassle because of conflicts from the last two commits.

a diagram demonstrating how git-filter-repo removes styles-specific commits (grey) from the lesson content commits (blue). The top git tree representing a styles lesson shows a git history that starts with styles and then branches to include lesson commits in parallel with styles commits with a merge commit. The bottom git tree representing a workbench lesson has the styles commits removed and the connections between commits are represented with orange lines. Two new commits in orange are added to the end of the tree that represent our automated commits.

If you want to be able to merge, it will be a bit of a hassle. You should make sure to use the transition tool from the tag of the release (e.g https://github.com/carpentries/lesson-transition/tree/release_swc/git-novice for the swc/git-novice lesson), and then transition your lesson locally.

From here, you may be able to merge the changes from the upstream fork into your local branch, but there will be a lot of conflicts. I think it is theoretically possible to merge the upstream in to the former HEAD commit of your local transformed lesson and then apply your changes on top.

gcapes commented 1 year ago

Thanks both for the replies! I'll schedule some time to have another read through before deciding what to do :smile: