Masterlist versioning

[Ortham]

@loot/looters: Opening this issue to discuss how to handle backwards-incompatible changes to the masterlist.

For example, LOOT v0.7.0 added support for:

• GitHub Flavored Markdown message formatting
• Message string substitution
• YAML merge keys

These are all useful things, but using them means that users that haven't yet updated will have a degraded experience, be it by having syntax errors or placeholder text instead of substituted strings, or just visible formatting markup.

How should we handle this? LOOT provides a couple of options:

1. Just start using them, with a global message for pre-v0.7 users that they may start to encounter oddities and errors, so really should update.
2. Create a new branch for each LOOT version that introduces backwards-incompatible changes. For example, I could ship v0.7.1 with the v0.7.1 branch as the default for each masterlist, and then that branch could be developed, while other LOOT version branches may get changes back-ported.

It's worth mentioning that v0.7.0 does break backwards compatibility in load ordering by default (by fixing bugs), but can be set up to produce the same load order as v0.6.1 did, so there's not really any reason why people can't update. Still, that may not be true in future, so in setting up a system it's probably worth bearing that in mind.

I think it's pretty clear that option 2 above is the better one, but it does add the potential for an increase in maintenance headache. To avoid that though, we could just say that

the latest LOOT version branch is the one that is "officially" maintained, and all others receive updates at the discretion of contributors.

I.e.

if you're using the latest version of LOOT, you'll get the latest masterlist updates, otherwise you may not, and if you don't like that, you can back-port the updates yourself.

In that case, the only real overhead of option 2 would be in branching for each LOOT release.

What do you think?

[kymckay]

:+1: Option 2

Anyone who doesn't update accepts that they won't necessarily receive the latest changes already

[Freso]

I think a branch per version-that-alters-metadata-format is a good way to go. Perhaps rename "master" into... what LOOT metadata format version we want to call that. :)

[Ortham]

Perhaps rename "master" into... what LOOT metadata format version we want to call that. :)

Well, we can't rename the master branch without breaking everyone's existing masterlist update, but to clarify all the branches the repo readmes could be updated to have a section explaining the branching system, and saying that the master branch belongs to the masterlist before it was versioned. I would also update the wiki to add information on the branching system.

I will probably release v0.7.1 this weekend, and I'd like to have versioning decided for that, so if @egocarib and @Sharlikran could also post their opinions that would be good. (That would give a majority opinion by number of commits. Well, I do that by myself, but I'm a benevolent dictator. :wink:)

[Freso]

Well, we can't rename the master branch without breaking everyone's existing masterlist update,

Right… Someone should go think about this two years ago and fix it since the first build. :stuck_out_tongue_winking_eye: (Speaking of going back in time, I feel I already did some discussion on this some time ago?)

[niveuseverto]

why to rename master branch? master can become "backward compatible branch" may be we should make "master" <-> "next" policy? overtime next branch will be merged into master and new next will be created (if needed)

[Freso]

@niveuseverto, "master" is usually the most recent code, either most recent stable or most recent experimental depending on how a team is using Git, but either way, some form of the "latest" version.

With the approach outlined as option 2 in @WrinklyNinja's post, "master" would be a <0.7.1 branch and all future masterlist format revisions will spawn new branches for their "format version". Having a simple two-tiered setup like "master"/"next" will not suffice, since some people will likely still cling to their 0.6.0 whenever the next masterlist format revision comes along. Continuously branching out is easy and cheap (it's one of the things Git was designed to do easily and cheaply) and will afford simple backwards compatibility without going through a ton of hoops.

The only downside, in my eyes, to this approach is that the masterlists' "master" branch will no longer be anything resembling the latest version of the masterlist. Which really isn't a very strong argument against going down this route.

[Ortham]

The only downside, in my eyes, to this approach is that the masterlists' "master" branch will no longer be anything resembling the latest version of the masterlist. (Which really isn't a very strong argument against going down this route.)

Hence the need to (or at least benefit of) explaining the branches in the repo readmes. Also note that you can change the branch GitHub displays as the default branch in the repo settings, like how the loot/loot repository has a master branch but dev is the default. I envisage that we'd change the default when a new version branch was made (which can help with things like making sure pull requests go against the latest revision).

[egocarib]

I also like the idea of new backwards-incompatible branches, which allows us the freedom take advantage of new syntax enhancements, and allows users the freedom to stick with an old version if they so desire. If we go that route, though, I don't forsee myself making any effort to port changes back to older versions of the masterlist.

[Freso]

@egocarib And that's fine. We're under no obligation to. If people want to use outdated software, they must be fine having an outdated masterlist as well. If not, well, pull requests are free. :+1:

[Ortham]

I have added a Masterlist Versioning wiki page to explain the system, and updated the Making A Release page to include the additional steps.

I have also created v0.7 branches in the masterlist repositories, and updated LOOT's code to use them, in preparation for the release of v0.7.1 tomorrow.

Still to do:

• [x] Add a link to the masterlist versioning wiki page to each masterlist repo's README.
• [x] Release v0.7.1.

[Ortham]

I've added a CONTRIBUTING.md file with a link to the versioning wiki page to each masterlist repo, so closing this.