Managing Editions of the book

[aterrel]

As discussed in other announcements, we would like to start making editions of the book. Starting this thread to discuss how to proceed.

[Iamanujosh]

I'm really excited about the possibility of contributing to the Versioning System for the book! I'd love to submit a proposal and start working on it. Could you please share any specific tools or approaches you'd recommend for managing book editions and versioning? I’m eager to get started and would appreciate any guidance!

[aterrel]

I would recommend looking at how other Jupyter Book projects do it. I started looking but haven't had time to figure it out.

[melissawm]

Hi all!

Here is a suggestion: for this handbook, I don't think we need the specific functionality of a version switcher, where specific pages can be checked in multiple versions. Rather, we can just point to a frozen version of the book the keep updating the latest version.

I've implemented that, adding links to historical versions of the cookbook in the left sidebar. This is a simple solution and feedback is appreciated.

If this sounds like a reasonable approach I can send in a PR for the source changes involved. Thanks!

https://melissawm.github.io/DISCOVER-Cookbook

[AR21SM]

hey @melissawm
Your approach to linking historical versions in the sidebar is a great step toward simplifying version management for the DISCOVER Cookbook. However, when navigating to a previous version, I noticed there’s no intuitive way to return to the latest version or switch between versions seamlessly.

A suggestion would be to implement a navigation system similar to how React handles its versioning

When visiting older versions, users are redirected to a dedicated page for that version (e.g., React's archived version pages).

Each page includes clear links or buttons to navigate back to the latest version or other historical versions.

Looking forward to your thoughts!

Best regards,
AR21SM

[AR21SM]

[AR21SM]

Hey @aterrel, @kamila-NF ,@melissawm
I've been working on the versioning system for the past week, exploring how others implement it and have recorded a demo showcasing my progress so far.

Looking forward to your feedback!
Best regards,
AR21SM

DISCOVER.Cookbook.DISCOVER.mp4

[melissawm]

This looks interesting! A couple of points:

• Let's make sure this implementation is accessible
• Does it work fine on mobile?
• If you can submit a PR with this proposal I think it makes sense to review.
  Thanks!

[AR21SM]

I’m currently working on the Proposal PR and will be submitting it soon with all the technical aspects of how I plan to implement the versioning system. I’m excited to get your feedback when it’s ready.

Have a nice day!
AR21SM

[AR21SM]

DISCOVER.Cookbook.DISCOVER.1.mp4

[Iamanujosh]

Hey @aterrel, @kamila-NF @melissawm

I've been researching ways to automate the versioning system for the DISCOVER Cookbook. Instead of manually managing versions, we can leverage GitHub tags to automatically generate and store different editions of the book.

In this video, I demonstrate how this can work seamlessly while keeping the workflow simple and efficient. This approach would allow users to easily access previous versions while maintaining the latest updates.

Would love to hear your thoughts on this! Looking forward to your feedback. 🚀

Screen.Recording.-.Mar.20.2025-VEED.mp4

Best,
@Iamanujosh

[melissawm]

Hi @Iamanujosh - to be honest, I think this is a bit overkill. We don't expect to have that many versions that often, so I would go with a simpler workflow. I'll leave the decision to the group, though.

[Iamanujosh]

Hey @melissawm, thanks for the feedback! I get your point about keeping things simple.

Maybe we could add a small automation step to make versioning easier without making it too complex? But if the team prefers a manual approach, I’d still love to help—maybe with improving the UI, making it more accessible, or updating the documentation.

Let me know if there’s any way I can contribute!