search

mt-mods / technic

Technic mod for Minetest
18 stars 24 forks source link

Technical guide to release management #122

Open S-S-X opened 3 years ago

S-S-X commented 3 years ago

I just added release https://github.com/mt-mods/technic/releases/tag/1.1.0

There should be some kind of release cycle guidelines but not necessarily complete feature freezes for next month etc.

It was not too easy to find what was actually changed and if all of it is still backward compatible, here's things that was changed between 1.0 (first) and 1.1 (just created that) https://github.com/mt-mods/technic/compare/4522961..master

So what would be good way to handle releases without affecting rapid development too much?

One way could be through adding tags when it feels like stable enough and low probability for big pull requests in next 7 days or something like that, again I don't think having too specific requirements is good but would be good to have some guidelines.

Okay you've added tag few days ago because you did feel that mod seems to be in pretty good shape, that was probably also tested in some servers for few days. If there was no problems, all tests are passing and tag has been there for few days at least then go hit "create release" button.

Suggestions?

OgelGames commented 3 years ago

Sounds like a good idea 👍

I think we should use changelog formatting for writing release notes though: https://keepachangelog.com/en/1.0.0 Example: https://github.com/minetest-mods/moreores/releases

OgelGames commented 3 years ago

I updated the releases with better release notes, if I missed anything or got anything wrong please correct it :wink:

BuckarooBanzay commented 3 years ago

I just added release https://github.com/mt-mods/technic/releases/tag/1.1.0

:tada:

There should be some kind of release cycle guidelines but not necessarily complete feature freezes for next month etc.

I think releases every few months or if something big has changed/was added would be nice (i guess thats what we are already doing :shrug:)

It was not too easy to find what was actually changed and if all of it is still backward compatible

We could start with a plain changelog.md file that has the same headers as the actual releases (https://github.com/mt-mods/technic/releases/tag/1.1.0) and update/track all the changes there on every PR/commit The file would have every old release plus an "upcoming" section that can be renamed on the next release. The example for moreores actually sounds good: https://github.com/minetest-mods/moreores/blob/master/CHANGELOG.md

One way could be through adding tags when it feels like stable enough and low probability for big pull requests in next 7 days or something like that, again I don't think having too specific requirements is good but would be good to have some guidelines.

as above: sounds good :+1:

S-S-X commented 3 years ago

I think releases every few months or if something big has changed/was added would be nice (i guess thats what we are already doing shrug)

Kind of yes, actually reason why I created release just now was actually fact that #119 is still open and not merged yet. So why it is good for release that it is not yet merged? Answer is it gives bit better compatibility if issues with LBM or node timers found later but not only that, old metadata wont be cleaned up so if there's some other horrible problems it will be significantly easier to do rollback before old metadata is destroyed and allows safely trying out latest features/fixes.

Metadata cleanup is kind of breaking change, that's also reason why I initially left it disabled with that hardcoded if false then thing.

OgelGames commented 3 years ago

We could start with a plain changelog.md file

I think that would be a good idea, the only problem is what to do with the 1.0.0 release, do we just put it down as "Initial versioned release." or do we put the changes made before that release (as I have done already)?

I think the easiest and best thing to do is just put it as the initial release, but I don't want to lose track of the changes made before it, because there are some major ones there...

EDIT: maybe we could just put the major changes in the readme, like we mostly already have: https://github.com/mt-mods/technic#notes

S-S-X commented 3 years ago

Dropping this here, probably good state for 1.2.0 release (or 2.0.0, TBD): https://github.com/mt-mods/technic/releases/tag/untagged-4b53be82de71a5edb41e

OgelGames commented 3 years ago

That link goes to 404 for me, but yes, I agree it's probably a good time for 1.2.0 release.

S-S-X commented 3 years ago

That link goes to 404 for me, but yes, I agree it's probably a good time for 1.2.0 release.

That was draft release linked to commit for release, seems that editing draft updates link... but draft should be visible here https://github.com/mt-mods/technic/releases/

BuckarooBanzay commented 3 years ago

Dropping this here, probably good state for 1.2.0 release (or 2.0.0, TBD): https://github.com/mt-mods/technic/releases/tag/untagged-4b53be82de71a5edb41e

1.2.0 sounds good :+1: , 2.x should be used for breaking changes (if there are going to be any :yum:)

EDIT: i just re-read the last sentence "Metadata loop removal is kind of breaking change for API because BA node state update is not anymore done with metadata." Is that part of the api even used?

S-S-X commented 3 years ago

Is that part of the api even used?

If some other mod registers another battery like node then yes. It has to update battery state to inform network about charge available, before it was done by writing metadata values but that was changed here: https://github.com/mt-mods/technic/commit/dd021f67829f48e5e2453b3019f9c6dd7783a8a7#diff-624c0e51d74dbeacd1d2f3c1f3c7295e4b8980d52381a40fa1572a9a7e2cb7c5

So now update with actual API function call is required instead of requiring known metadata values. API call that replaces metadata is network:update_battery(current_charge, max_charge, supply, demand).

Access to network object is new feature, way how battery state is updated is new feature. Communicating changes through metadata values is removed. Not sure if old way through metadata even really can be considered to be public API or if there's actually any external users for it.

S-S-X commented 3 years ago

Added release as 1.2.0

Notes from draft:

Was there breaking changes with chests and/or SCI?

OgelGames commented 3 years ago

FYI, I updated the 1.2.0 release with more details of the changes in that release.

for me looks like not breaking changes for SCI

Correct, it should even be backwards compatible.

was technic chest register function compatible for external use? if it was is it still compatible?

Not really, it could have been used, as it was a global function, but it wasn't a proper API. (and still isn't, but we have #117 for that)

The name of the function did change though (and may change again when it's improved): https://github.com/mt-mods/technic/blob/1113c93a2609afee8305541d833d53343153e888/technic_chests/register.lua#L406 https://github.com/mt-mods/technic/blob/b94767608b5d4587a621b59ebc68f83b2aeeaffb/technic_chests/register.lua#L51

S-S-X commented 2 years ago

We might want to create some rule for 1.x version patches if we're going to manage semantic versioning. See #218 comments, also relevant question there about versions:

Should we possibly create another release (or directly switch to rolling releases)? Originally posted by @BuckarooBanzay in https://github.com/mt-mods/technic/issues/218#issuecomment-946087034

For now I've added protection rule for branch names matching 1.* after restoring 1.2.1.

OgelGames commented 2 years ago

Makes sense to keep 1.2.x maintained, at least until 2.x is released.

~Probably should see what other changes could be added to 1.x and release 1.3.0, the most recent commit 060f97f being one of them.~

Edit: 1.2.0 was the version-breaking release, which is why only 2.0.0 can be the next feature release.

S-S-X commented 2 years ago

Makes sense to keep 1.2.x maintained, at least until 2.x is released.

~Probably should see what other changes could be added to 1.x and release 1.3.0, the most recent commit 060f97f being one of them.~

Edit: 1.2.0 was the version-breaking release, which is why only 2.0.0 can be the next feature release.

I don't see any public API changes or new features in 060f97f, I see only fixing bad behavior.

edit. Actually yes there's right click toggle... which can be easily left out if looking for simple performance updates that can be included for ContentDB release.

S-S-X commented 2 years ago

Started going towards next release, closed few issues that affect upgrading and looked at milestones list. Dropped #147 as it is not needed, it is feature upgrade and there's already huge amount of new features in addition to breaking API changes. That one can be added as feature release.

Other issues are actually breaking things changing API and good to have for v2 milestone. However I think for some things it should be considered to attempt keeping backwards compatibility, mostly registration functions in public API. (#117)

OgelGames commented 2 years ago

Sounds good, it's definitely a good idea to include any breaking changes in 2.0.0, to avoid having to bump to 3.0.0 too soon 👍

S-S-X commented 2 years ago

I've been thinking a bit about possible issues caused by 2.0 release, especially if mod is released to ContentDB. There might be more issues than just this but to collect possible issues and make it easier to make final release decisions:

OgelGames commented 2 years ago

... to provide and advertise package system that crashes their game

None of the changes we make should cause crashes, only break functionality.

for mixed versions it would be simpler to just override relevant pieces in other mods

IMO that just creates more problems in the future, and stops the progression of moving forward and having mods get updated.

Should ContentDB release be delayed until everything else is up to date there?

Possibly, though there's really only a handful of mods that will be affected by the changes, and only three that will have functionality be broken. (I may be wrong on that number)