Problem/Motivation
With the upcoming release of Drupal 10 we are seeing more projects update to a new major version. Typically a new major verison is not the end of the world, but for many modules that have downstream dependencies, it can make creating cross-compatible support between 8,9,10 versions more difficult than it needs to be.
In truth, a new major version should only be created when a backwards compatibility change is absolutely necessary
For more examples of when cutting a new major can cause issues, this blog from @japerry has good use cases: https://medium.com/jakob-on-drupal/dont-go-making-major-version-changes-...
At the same time - it can be an *enormous* headache for Drupal Association staff to try and fix things if releases go off the rails after the fact. Unpublishing is something we *never* want to do.
Proposed resolution
To mitigate the problem - we could add help text to the release form to explain when and why to cut each type of release (patch vs. minor vs. major) and also considerations for when to switch to the semver format if a project has not already (many don't need to do this because D.O translates the version strings.
We should also review any existing warnings to make it abundantly clear that releases won't be able to be unpublished/deleted once created - 'Are you sure?'
Remaining tasks
- We need to draft the help text.
- If we need more space than we can do right on the form, we should also link to more detailed documentation.
- We need to implement the changes.
User interface changes
Help text appearing on the new release form.
| Comment | File | Size | Author |
|---|---|---|---|
| #10 | Screenshot 2022-09-14 at 11.28.55.png | 35.22 KB | fjgarlin |
| #7 | Screenshot 2022-09-06 at 16.02.43.png | 64.42 KB | fjgarlin |
| #5 | Screenshot 2022-09-01 at 10.52.41.png | 71.6 KB | fjgarlin |
Issue fork drupalorg-3306964
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments
Comment #2
hestenetComment #3
japerrysemver.org:
MAJOR version when you make incompatible API changes (Emphasis added)
Projects, especially larger ones or ones that are a dependency in an ecosystem should think long and hard before they increment the major version. At a minimum, there should be a meta issue discussing the next major version, what goes into it, and what major versions of core you're supporting. (its too bad we cannot link the 'major release' tag to a major issue)
Some type of wording like:
"Bumping the MAJOR version of a release should be done with caution. If a major version is being considered due to upstream compatibility, please review core compatibility best practices (add link that doesn't exist yet)"
-- Which reminds me, I don't think we have a good d10 compatibility guide. We have made some for d10 at Acquia, and Matt and myself have both blogged about it. But nothing is in a concise guide on drupalorg. Thats probably worth expediting as we get into D10 beta.
However, I'm not saying you should never increment a Major because of upstream dependencies, just that its a bit nuanced and most modules should try to be backwards compatible. The default mindset of maintainers should be 'stay on same version' until there is a breaking change that cannot be coded around.
FWIW:
https://github.com/semver/semver/issues/864
https://github.com/semver/semver/issues/14
Comment #4
cmlaraI'll admit from conversations I've had I'm probably in the minority here on D.O. however contrary to the above blog post I tend to view dropping Drupal Core versions as a change justifying a major bump in most cases and I hope we at least make the tooltip not seem rigid.
A large part of this comes from the fact that semver has evolved to be used by modules that are not api providers.
Why I generally feel dropping core support should be a major? Because for most modules Drupal is generally not just a dependency but rather its a supported operating environment. Its similar in concept to dropping support for a version of PHP (which Drupal is moving towards doing in D10, part of the reason I'm sure I'm in the minority though they are at least coding it so it arguably has become part of the API) or dropping support for an entire operating system. To put this in context of the already provided semver links Dropping Core could break the build process for sites that utilize your module.
There are arguments that since we use Composer as part of the tool-chain we are prevented from breaking by prohibiting downloading a version of the module that is not compatible however recent issues with modules shows that may not be enough at the moment inside the Drupal ecosystem.
Poor dependency management by contrib isn't solved by recommending keeping the same major version, its just delayed. I know we have had two issues lately with modules that are used that contrib may have depended on an open ended dependency, however they will still break eventually when a real API break occurs, and if there is no API break they should not break at all even even if the major is increased unnecessarily. The primary downside with major bumps is that periodically someone needs to come in to contrib and increase the versions they are compatible with to extend their supported range.
For additional consideration:
https://github.com/semver/semver/issues/526
Comment #5
fjgarlin commentedThis is the message shown when there are no new branches or tags:

Perhaps we can extend/adapt that message and display it as well when adding a new release.
Comment #7
fjgarlin commentedSomehow the MR is not showing. It's here: https://git.drupalcode.org/project/drupalorg/-/merge_requests/120/diffs
I've abstracted the message and just changed the title when we are adding a new release and there is no error. The message will display like this when adding new releases:

Comment #8
drummThat message is quite large in this context. Maybe we should just show a more-brief message linking to the naming conventions page.
I’m not sure how practical it is to explain what should be a new major/minor/patch version on the add release page itself. If its hard-coded, it'll be harder to update. And it needs to be brief and readable to have a higher chance of being read.
Comment #9
fjgarlin commentedAdapted the code to show a shorter version when adding the release. See below:

Please review and/or suggest text/links for the message.
Comment #10
fjgarlin commentedComment #11
fjgarlin commentedAddressed the above feedback.
Comment #13
drummThis is now deployed.