Plan for updates about jupyterlab_xkcd

[blink1073]

@parente, thoughts?

[parente]

I started to use branches at certain commit points originally, but quickly found that it was really hard to follow the history as a tutorial reader. I went to tags as a stop gap and started rewriting master just to get a first version prepped with a reasonable history.

Going forward, I'd like to see the clean git history retained for readability, but agree we need a way to version what's here to match JupyterLab versions at a minimum, if not tutorial versions. I'm not sure how to fit that with a traditional PR workflow.

[blink1073]

Okay, let's assume a single branch. What we could do is have a "rotating" set of commits that are scoped with the appropriate version (e.g. v0.27-01-foo). After a release of JupyterLab, we create a new PR against this repo. We start from the markdown (or notebook), updating both the document and this repo, creating the new tags along the way. We merge this PR first, so the links in the tutorial document are live, and then merge the JupyterLab PR.

[parente]

Maybe this is what you were suggesting to start and I just figured it out: how about having a long-lived branch per jupyterlab release (e.g., v0.27) with tags like you suggest on that branch (v0.27-01-foo)? If there are mistakes on those branches, instead of making PRs, we can fix by rewriting history to keep the flow clean. It won't make contributing all that simple, but the tutorial is really the system of record here and the code repo is just a reference.

I think GitHub lets you choose which branch appears as the default when users land on the project page. We could flip to the one matching the latest stable release of JupyterLab, or the latest branch that remains compatible.

[blink1073]

Ah, so the branch history has only the commits referenced in the tutorial?

[parente]

Yes. Just an idea. Why do you think?

[parente]

Mobile. Sorry. What, not why.

[blink1073]

Okay, so I'll create a branch for 0.28 using git checkout --orphan 0.28 and use the tagging pattern. Then we point GitHub at that branch as a default (I've seen other repos change the default branch).

[parente]

Thanks. Let's see how it goes. If it turns into too much work, we can find another way.

Let me know if I can help at all.