Ideas for Versioning a Digital Publication

[daniel-keller]

Hi everyone!

I'm interested in learning how other museums have handle versioning their digital publications. Is it common practice to use semantic versioning like with any other software? Do you mirror conventions used when versioning a physical publication? Or should a combination of both be used where code releases (which may happen more frequently then a publication revision) don't have a one-to-one correlation with editions (e.g. 1.0.0-ed.1, 1.0.1-ed.1, 1.1.0-ed.1, 2.0.0-ed.2, 2.1.0-ed.2, etc.).

I'm also looking into the best way to deploy multiple editions of a publication. We use github pages for our clowes catalog deployment but given the size of our catalog (~3GB) deployment takes ages and sometimes exceeds github's timeout. I'm thinking deploying more than one build (edition) of the catalog to the same repo probably won't work. I could setup different repos for each edition but that doesn't scale well once I get beyond more than a few publications each with multiple editions.

[geealbers]

Hi @daniel-keller, interesting question, and I'm intrigued by the idea of publishing multiple editions. Here's what we currently do at Getty ...

During the development process, we use different branches for main each phase of work, and then create a versioned GitHub Release when each phase is complete. So, the first-pages branch becomes release 0.1.0; second-pages is 0.2.0; and final-pages is 0.3.0. Some minor edits made to one of these phases would mean a new release, like 0.1.1 for a revision to the first pages phase. When the book is published, we create a 1.0.0 release, and revisions to that would subsequently be versioned and released. A second edition of the book would be 2.0.0, however, our editors have a high bar for what constitutes a new edition as opposed to simply a revision, following Chicago Manual of Style's guidelines quoted below, so it's unlikely we'll be looking at a true second edition of any of our Quire books in the near future.

Edition (as opposed to impression, or printing) is used in at least two senses. (1) A new edition may be defined as one in which a substantial change has been made in one or more of the essential elements of the work (e.g., text, notes, appendixes, or illustrations). As a general rule, at least 20 percent of a new edition should consist of new or revised material. A work that is republished with a new preface or afterword but is otherwise unchanged except for corrections of typographical errors is better described as a new impression or a reissue.

Then for deploying our publications we use Netlify, which is hooked into our GitHub repo for any given Quire project and builds and deploys the site automatically with every push. They also have a great feature that allows you to deploy from multiple branches in the same repo. So, we end up with a URL for each of our development branches (first-pages, second-pages`, etc.). We then set up a URL proxy to map the Netlify URL to a getty.edu one for the final book. For our final published books, we are not publishing multiple editions simultaneously as you're proposing so we're just doing one proxy and are not making our development branch URLs public, but it seems like the basic approach might work well for your use case.

One final note, Netlify recently changed its pricing structure and this made it untenable for Getty to continue hosting Quire books with them due to the overall size of our GitHub org. So we'll be changing our deploy methods soon, but I'd still recommend checking out Netlify, we've been really happy with them.