Repository navigation
Portable version outdated compared to web version #266
Description
👋 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.
Activity
semioticrobotic commentedon Sep 4, 2026
👋 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 commentedon Sep 4, 2026
I had completely missed other repos on the org! I'll dig in there and see what I can learn as well. 🫡
sanchuanhehe commentedon Sep 4, 2026
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 commentedon Sep 4, 2026
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-epubartifact: https://github.com/theopensourceway/production/actions/runs/33895148933The 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 commentedon Sep 5, 2026
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:
testingbut for a book) available on GitBook and updated as soon as new additions are mergedI 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 commentedon Sep 7, 2026
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 commentedon Sep 8, 2026
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?
sanchuanhehe commentedon Sep 9, 2026
I think we are very close—the main building blocks are already in place. HTML, PDF, and EPUB are built and validated automatically, and the Pages deployment is working.
What remains is mostly the final orchestration: trigger the production workflow from a guidebook release tag, build from that exact tag, publish the downloadable artifacts, deploy the website under
/production/<tag>/, and update/production/to the latest stable release.I would consider this a relatively small additional investment: probably one focused follow-up change and validation during the first automated release. The only part that may require owner or admin involvement is authorizing the cross-repository trigger.
semioticrobotic commentedon Sep 9, 2026
Very good! I opened theopensourceway/production#13 to track this additional work, and believe was can now close this issue. Thanks for spurring this additional iteration, @cassidyjames!