Silverstripe-framework: RFC-9344 Remove branch aliases

Created on 2 Dec 2019  路  16Comments  路  Source: silverstripe/silverstripe-framework

Remove branch aliases

Status: Accepted

Abstract

The RFC argues the branch aliases might not be necessary to solve the problems we're trying to solve with them and the benefits are not worth the maintenance cost.

Intro

Silverstripe modules follow semantic versioning and branch naming conventions.
In short, here are the naming convention:

  • master branch contains the next major version (unreleased)
  • _major_ branches (<positive digit>) contain released major versions and all the changes for unreleased minor versions
  • _minor_ branches (<positive digit> "." <digits>) contain released minor versions and all changes for unreleased patch versions

Examples

Here are some examples around the framework repository.

At the moment of writing, we have Silverstripe CMS 4.5.0RC1 to be the latest minor version.

  • master contains everything yet to be released in 5
  • 4 is a _major_ branch and contains everything yet to be released in 4.6
  • 4.5 is a _minor_ branch and contains everything to be released in 4.5.1

The branch 4.6 does not exist yet.
As such, the branch 4 temporarily takes the responsibility of 4.6 until it is created.

Branch aliases

Our current convention around branch aliases is that _major_ branch makes itself to be the alias of the next minor release.

Here is what it looks like:

  • framework:4/composer.json has alias of "4.x-dev" : "4.6.x-dev".
  • reicpe-core:4/composer.json has alias of "4.x-dev" : "4.6.x-dev" and requires aliases framework:4.6.x-dev, assets:1.6.x-dev
  • recipe-core:4/.travis.yml requires aliases 1.6.x-dev of extra libraries (e.g. versioned:1.6.x-dev)

Problem statement

A lot of manual work to maintain branch aliases

When creating new minor releases we generate new branches for the modules.
This is automated and we have a tool called cow that removes aliases from the new branches. However, after that, we have to go through all the modules and manually patch the branch aliases, which includes:

  • update composer.json and add extra.branch-alias (if its deletion has been merged-up or update if wasn't) (https://github.com/silverstripe/recipe-core/commit/79f84ad158168cda5376780be8f6a0569c6cfaeb)
  • update composer.json dependencies, so that module includes the new aliases of requirements (unreleased minor) (https://github.com/silverstripe/recipe-core/commit/9857cc54efec2d213622ee2a0559a29f1190a8e6)
  • update .travis.yml COMPOSER_ROOT_VERSION (https://github.com/silverstripe/recipe-core/commit/79f84ad158168cda5376780be8f6a0569c6cfaeb)
  • update .travis.yml testing requirements to include aliased versions (https://github.com/silverstripe/recipe-core/commit/79f84ad158168cda5376780be8f6a0569c6cfaeb)

Benefits

I was asking around trying to figure out what benefits branch aliases provide and here are some findings

It is a way for users to pre-use unreleased minor versions

Otherwise, users would have to set their constraints to 4.x-dev, but then the user would be continually bumped up minor versions whenever we made a new branch, so it's a way for users to control that.

Avoiding breaking builds when we release a new minor version

We can set up Travis builds that require 4.6.x-dev before the 4.6 branch is created (it'll be on 4 branch). When we eventually branch 4 into 4.6, and re-vendor 4 as 4.7, then those builds continue to work.

Proposal

I believe we may be able to remove branch aliases altogether without losing anything, but reducing the maintenance burden of updating them manually for every release.

Here I'm going to address all the benefits mentioned above one by one:

It is a way for users to pre-use unreleased minor versions

My opinion is that most use cases are covered by simply switching to 4.x-dev branch. Otherwise, we should discourage using unreleased versions in recipes that may hit production.
However, if that is a requirement to someone we could recommend using >=4.6.0 <4.7 || 4.x-dev
in conjunction with "minimum-stability": "dev", "prefer-stable": true.

In that case, the recipe should pick up 4.6 when it gets released without relying on branch aliases.

Avoiding breaking builds when we release a new minor version

Our current release process includes a feature freeze step when we create new branches some time ahead of releasing the stable version. In that case, we have some time to go through all CI builds and fix the configs of new branches if necessary.

On the other hand, if we update _major_ branches to require _major_ branches of dependencies, then we won't have to change those configs anymore. For the newly created version branches, we should be able to patch their requirements when we create those (feature freeze).

Suggested steps

  1. Remove all extra.branch-alias directives from every repository.
  2. Update _major_ branch dependencies of recipes to require _major_ branches of libraries (e.g 4.x-dev requires 1.x-dev and 4.x-dev)
  3. Update _major_ branch Travis configs to require _major_ branches of dependencies
    e.g. silverstripe/framework:4.x-dev has COMPOSER_ROOT_VERSION=4.x-dev and requires postgres:2.x-dev, recipe-core:4.x-dev and admin:1.x-dev

PRs

rfaccepted
Source
picture dnsl48
👍5

All 16 comments

Please, let me know if I forgot to mention any other benefits of branch aliases.

dnsl48 picture dnsl48 on 2 Dec 2019

Can you provide an example of how you鈥檇 configure the admin module (for example) Travis builds for a 4.6.x release once you decide to switch it from major branch constraints, eg at the time when we assemble a beta release?

robbieaverill picture robbieaverill on 2 Dec 2019

Can you provide an example of how you鈥檇 configure the admin module (for example) Travis builds for a 4.6.x release once you decide to switch it from major branch constraints, eg at the time when we assemble a beta release?

I imagine that would imply creating a new branch 1.6 for silverstripe-admin repository first.
Then, within the new branch we would patch the following:

  • .travis.yml:

    • COMPOSER_ROOT_VERSION updated from 1.x-dev to 1.6.x-dev

    • RECIPE_VERSION updated from 4.x-dev to 4.6.x-dev

    • composer require silverstripe/versioned updated from 1.x-dev to 1.6.x-dev

    • potentially could patch postgresql and sqlite deps too

dnsl48 picture dnsl48 on 2 Dec 2019

Gotcha, so you鈥檙e proposing that we remove the branch alias pointing at the next minor release. I think I鈥檓 on board!

robbieaverill picture robbieaverill on 2 Dec 2019
❤1

Ping @silverstripe/core-team for feedback please.

maxime-rainville picture maxime-rainville on 2 Dec 2019

I'm in favor of removing the branch aliases. Every release, a poor dummy has to go through each repo and increments branch alias and tweak travis builds. That waste about a day of dev time and it's error prone. It's not a process that can be automated because each travis build is a little bit different and will require slightly different versions of various things.

Sounds like a lot of wasted time for making it slightly easier for some people to run pre-release code.

maxime-rainville picture maxime-rainville on 3 Dec 2019

Sounds like a lot of wasted time for making it slightly easier for some people to run pre-release code.

Yep, that. Great write-up and initiative Serge!

chillu picture chillu on 3 Dec 2019

So sounds like three core committers are on board, and another "contributing committer" who's directly impacted by this (Serge). I'd give it another day for other core devs to weigh in, but I doubt that it'd be controversial. In terms of timing, there's no reason for this to coincide with a recipe release, right? Removing the branch aliases will break some people's composer constraints, but frankly if you are pinning to 4.6.x-dev before a 4.6 is even tagged for a beta release, then you shouldn't necessarily rely on this behaviour in mission critical contexts, right? Either way, we need a comms plan. I'd suggest a forum post, tweet and community slack message linking to it.

chillu picture chillu on 3 Dec 2019

I'm happy to support this.

Under your suggestion for "It is a way for users to pre-use unreleased minor versions", it would be good if you could test whether this works instead of >=4.6.0 <4.7 || 4.x-dev:

^4.6@dev

That will also allow 4.7+, but that's usually okay.

My understanding is that 4.x-dev resolves to 4.9999.9999.9999-dev internally, which would satisfy ^4.6@dev

sminnee picture sminnee on 3 Dec 2019

would be good if you could test whether this works instead of >=4.6.0 <4.7 || 4.x-dev

Yes, it works, but that allows installing 4.7+ as well. Agree, that's another viable option.

there's no reason for this to coincide with a recipe release, right?

No, all the aliases have already been updated to refer to the next minor.

we need a comms plan. I'd suggest a forum post, tweet and community slack message linking to it.

Fair enough. I'm not sure about a tweet though. It feels a bit too technical to me :)

dnsl48 picture dnsl48 on 3 Dec 2019

Yes, it works, but that allows installing 4.7+ as well. Agree, that's another viable option.

I'm not aware of a case where we want to allow an unreleased 4.6 version in a dependency but not allow installing 4.7+ :P.

sminnee picture sminnee on 3 Dec 2019

Fair enough. I'm not sure about a tweet though. It feels a bit too technical to me :)

Yeah we should start using the forum as a more coherent comms channel anyway, and get people in the community used to actually checking in there, because it contains valueable info.

chillu picture chillu on 3 Dec 2019
👍1

Here we go: https://forum.silverstripe.org/t/rfc-to-remove-branch-aliases/2493

dnsl48 picture dnsl48 on 3 Dec 2019
👍1

So far 4 core-committers approved and we don't have any arguments at all against deleting aliases.

We're planning to accept this RFC and start deleting the branch aliases next Monday: 2019-12-09

dnsl48 picture dnsl48 on 4 Dec 2019
👍1

Branch aliases* I assume you meant

robbieaverill picture robbieaverill on 5 Dec 2019
😄1

Hi all, there is some confusion around this RFC, so I've drafted an amendment to it - see https://github.com/silverstripe/silverstripe-framework/issues/9560

robbieaverill picture robbieaverill on 26 Jun 2020
👍1
Was this page helpful?
0 / 5 - 0 ratings

Related issues

jonom picture jonom  路  5Comments
Cheddam picture Cheddam  路  3Comments
Martimiz picture Martimiz  路  5Comments
chillu picture chillu  路  3Comments
Cheddam picture Cheddam  路  3Comments