Portable version outdated compared to web version

[cassidyjames]

👋 Hello friendly Open Source Way contributors/maintainers! I absolutely love your work and have been obsessively reading and rereading it lately. Excellent stuff.

I grabbed the portable version for my ereader and noticed it’s the 2.0 version, not 2.2. I poked around the repo and wiki a bit to try to understand the portable publishing process but haven’t had success in figuring out how it works.

If I can be pointed in the right direction, I would be happy to help automate or at least document things to keep the versions in sync.

[semioticrobotic]

👋 Hey, @cassidyjames! So glad to see you here. And thanks so much fro your kind words. If it isn't already, I think "open source obsessives" should be a phrase we use to describe the guidebook's target audience. 😁

Thanks very much for flagging this and opening this issue. The truth is that we've just finished a pretty substantial overhaul of our production tooling and haven't yet iterated far enough to get ePub builds into the publishing process. But this is definitely something we'd want to have @sanchuanhehe take a look at.

Ultimately, the goal is to reposition some things so that the website and portable versions are the "snapshotted" and current production versions and the GitBook version is the "production+1" version. I'm waiting on @sanchuanhehe to let me know the production tooling is working as expected before I make these changes.

@sanchuanhehe: Does this seem like something we're able to do with the new tooling you've established?

[cassidyjames]

I had completely missed other repos on the org! I'll dig in there and see what I can learn as well. 🫡

[sanchuanhehe]

Yes. The current production pipeline is working as expected, and I believe it is ready to be adopted as our official production path. This is also one of the issues the new infrastructure was intended to address.

@cassidyjames, you can find the latest successful pipeline run and its current HTML/PDF artifacts here: https://github.com/theopensourceway/production/actions/runs/28499106762. Adding ePub output to the same pipeline should be straightforward.

@semioticrobotic, I think we can start moving forward with the formal adoption of the new infrastructure. Should we begin by updating the current HTML/PDF release and website download process, then add ePub, or handle them together?

[sanchuanhehe]

Update: ePub output is now implemented in the production pipeline. The latest successful run builds and validates both English and Simplified Chinese EPUBs and publishes them in the guidebook-epub artifact: https://github.com/theopensourceway/production/actions/runs/33895148933

The implementation is in theopensourceway/production@574e549. The remaining step is deciding how to include these artifacts in the formal release and website download flow.

[semioticrobotic]

This is wonderful, @sanchuanhehe. Thank you.

Version 2.3 of the Open Source Way guidebook is now available. I bundled all the artifacts from @sanchuanhehe's new production tool and offer them as a single archive of portable versions (👀 @cassidyjames!). I have also updated the project website to more clearly guide readers through our offerings:

• The current production version (2.3) of the guide on the web
• Our bundle of portable editions of that same edition (v2.3) available for download and offline reading
• Our "production+1" working draft guidebook (think Debian testing but for a book) available on GitBook and updated as soon as new additions are merged

I hope you're all as excited about this latest release as I am. But naturally if something can be improved, please let's discuss!

[sanchuanhehe]

Thank you for putting this release together. I think the next improvement should be to automate this process end to end.

Ideally, a release tag in the guidebook repository would trigger the production pipeline to build and validate the HTML, PDF, and EPUB outputs from that exact tag, publish the downloadable artifacts, and deploy the web edition to a versioned URL such as /production/v2.3/.

The current /production/ URL could continue to point to the latest stable release, while previous versions remain available at their corresponding versioned URLs. This would make each published edition reproducible and reduce the manual work required for future releases.

[semioticrobotic]

This would be an incredible boost to our current (largely manual) release process, @sanchuanhehe—no doubt about it. How possible do you believe it to be, and with how much relative investment?