Versioning and the Starter Site

[Rosie Le Faive]

You may notice there are some Tags and Releases in Github for the Starter Site, and I want to explain what they're for.

As I've said (too many times), the Starter Site wants to help you start up your own Islandora-ified Drupal, but it's your responsibility to maintain the site once it's made. The Starter Site repo cannot be used for updates.

As we (the community) find better ways of doing things, we can work together to change the defaults that you get in the Starter Site, by having discussions and sprints and making pull requests against the Starter Site (etc). 

The method that seems best for communicating these changes to the Starter Site is: Release Notes in Github. It's a standard location for release notes, there's tons of space to use markdown, and you can scroll through the list of them, they're datestamped and authored and they're connected to the code changes (if you want to see them).

Unlike normal release notes, which inform you of what happens when you install an update, the Starter Site release notes are more of a recipe or pattern for you to follow along on your own site. (recall: starter site repo cannot be used for updates).

This means that you have total control of what changes you choose to bring into your site, and how they work! It might even inspire you to come up with something better! And if so, please share :) 

So the two releases created today are an example of such "Release Notes" - one of them (the older one, 0.1.0) includes a link to an explainer document because one change was rather extensive. I think that's a pattern we will try to follow: 

• Bullet points of what simple drupal changes were made
• Links to longer explainers where needed when the change is complex.

We're going to focus the "Changes to Drupal" section(s) on what a Drupal site admin needs to do to re-create the changes we made, so it may include things like "update such-and-such module to at least version x.y.z so you can use this new feature". Or "apply this patch" (hopefully not very often!!!). There will also be changes that aren't relevant to include in this section of the release notes, like changes to the.gitignore files or the README.

Also, I found this composer-lock-diff tool which makes it super easy to calculate the change to module and dependency versions, and paste it as a table into release notes. For example I used composer-lock-diff --from 0.0.0 --to 0.1.0 --md to get the 0.1.0 release notes. 

And a note explaining the silliness of the tags: I created an arbitrary start tag in early December (tag 0.0.0) when we started working on the starter site in earnest. It doesn't really mean anything. I wanted to bracket the December sprint so I could write release notes about just that.

When we create a tag/release (soon, hopefully!) that requires that you use PHP 8, then that is going to be a breaking change. It will require software be in ISLE/Playbook that wasn't necessarily there before. Per SemVer rules, it will be tag 1.0.0.  But it does not imply (this is why i'm calling it semantic-like) that the Starter Site is in any way "ready" or at a "stable" release - we're still in full flux. We're getting there (thanks to lots of work by lots of people) and we invite you to come and try it. 

TL;DR: Starter site has versions/releases now. It's a good place to put release notes. The version numbers reflect compatibility with ISLE/Playbook so we don't get into this PHP 7 vs 8 stuff again.