stable main, unstable dev, semver

[pciavald]

As downstream of this project, we will start relying on the main branch of the repo and on version numbers to find breaking changes.

Would it make sense for you to start using a dev branch to push unstable changes and new features that we will help testing, and keep the main branch for stable software and point releases ?

Also i've noticed your next milestone is v4. Following semver, it would mean you're planning to make breaking changes for that version. v3 did break the configuration folder, but translations for instance should not, and probably should be in milestone v3.1 instead.

What do you think ?

[pciavald]

@UnchartedBull if you grant me the repo access i could create the branches, not disturbing your current workflow but i guess the release schedule is what's blocking you to merge #1610 which in turn blocks #1627. The former is ready and could be merged in dev as main would still represent your upcoming release.

[UnchartedBull]

I'm totally fine to merge #1610 before the v3 release, just hadn't had the time to check it out and review it.

What would be the advantage of the unstable / dev branch? I'm a huge fan of feature branches and they should be merged once they're complete & stable on a dev setup. You then have tags to mark releases in the main branch which indicates a fully stable state, so I've never really understood the need for a dev / unstable branch. Maybe you can enlighten me here :)

Regarding the versioning, I'm trying to use some kind of semantic versioning, it isn't fully applicable to OctoDash, since there are no outward facing APIs or similar. Thus a increase in major version usually means some bigger changes (i.e. including Touch functionality, switching to websockets). Minor releases are then some new features, while patch releases are mostly a single feature / bugfix. So it's kinda semver, but not fully compliant.

I just named the project v4, which will basically include all features that are going into v4, this doesn't mean that there won't be a v3.1.0, if there are enough new changes added. V4 probably won't be released for quite some time, since most of the stuff now is minor fixes / improvements. I think it will be too much overload to create a milestone / project for each minor release, plus I don't know yet what will be included in v3.1.0.

[UnchartedBull]

Oh and I'm going to assign the contributor state to you so you can create your feature branches on the main repo if you like, just need to configure some stuff in the repo beforehand :) Thanks for all your work!

[pciavald]

Here's how i see it:

• main is for releases and hotfixes, as people who clone main expect it to work like a release. It accepts merges from the dev branch and hotfixing branches, which should not happen, but could, in case a corner case was not tested on dev and an issue arises just after the release. Hotfixing usually only bumps the last number of the version
• dev is to merge the merge requests (feature and non-hot fix branches). It allows to merge pull requests without destabilizing main, as it happened when I opened this issue: main was in an unstable state after merging the websockets mega-PR, so when we pulled main our software was not working anymore, which would have been expected of dev but not of main.

Feature branches are thus unchanged. I agree that PRs should be merged "when they're complete and stable", but it's hard to guarantee that before merging. That's why tests are usually ran on the dev branch after a merge, to make sure the PR was successfully "integrated". (we plan to create a functional test suite for octodash)

About #1610, it's a typical example. Other PRs need it to be merged which creates pressure to get it merged, which currently leads to rushing its merge to main, while we could discover some incompatibility after the merge.

I see the opinion that main should be considered unstable outside of release tags, but that's not common practice and users cloning main usually expect it to be stable.

Regarding versioning, I see and agree with your point. The only "APIs" i see in octodash are the config file (broke on our side from v2 to v3) and the themes (#1623 and #1654 may break). I usually use milestones to group PRs that were included in a version in order to facilitate writing the changelog. Let's take current v3.0.0. When i make the release, i create the next v3.1.0 milestone. When i add a bugfix before that next release i create the v3.0.1 tag. when a feature looks too big or breaking, i create v4.0.0 and assign it.

[pciavald]

Could you please give me the rights to edit issues ?

[pciavald]

If you agree to doing this, I think this should be done for the event of v3, tag it on main when ready then we will create a dev branch from main and set dev branch as default target for PRs. #1675 is another example of why we need it IMO 🙂

[UnchartedBull]

Had a look around and I'm still not a fan of the dev branch. It seems more like a chore to merge this into main. Plus if dev would be a branch where unstable code would be merged the whole code would need to be reviewed before merging into master and I don't really fancy a 1000+ lines PR.

The CI/CD pipeline should run for every Pull Request (which it already does) and then for every commit on main (which it does as well), so there is a very low chance that something is very broken on main. Some stuff might not working 100% correct, but that's to be expected if you install something you build yourself.

You can also create PRs based on other PRs, this then creates no pressure on anyone and would mitigate the need for the dev and main branch.

Current changelogs are generated based on actual release tags, but I guess we can keep the Milestones and ditch the Projects in favour of them.

[pciavald]

I do not think that self-built open-source software should be expected to fail, see gentoo, but I respect your opinion. We will change our downstream architecture to treat the main branch here as the usual dev.

[UnchartedBull]

I think there are multiple examples for either. I.e. VSCode also doesn't use a dev branch. But good that we found a working mode that works for both sides :)