Maybe use semantic versioning and semantic release?

[buehler]

Hey @ferrarafer and @FilledStacks

I don't know which versioning strategy you use in this repository, I just wanted to pitch an idea. In my other repositories, I use semantic versioning in combination with semantic-release. Do you know about the system and/or have you considered it?

As far as I know, it does not work well with mono-repos, but it does a pretty nice job at updating versioning numbers, changelogs, and the likes.

As an example: https://github.com/smartive/zitadel-dart
When the repository is updated, semantic release will determine the new version, update the pubspec and the changelog according to the commit message and then pushes the latest version to pub.dev. All fully automatically. You could even do pre-releases if configured.

Wdyt?

[FilledStacks]

@buehler that's a great idea, I haven't used it but the more we can automate the happier I would be. I'm very open to it.

We haven't had the time to solidify our pipeline and automate this process. Because we're currently only building stacked based on our requirements it's always a code -> immediate release type thing, if the CI passes.

With that said this would be a welcomed feature. I'm currently forking the AutoRoute package into our generator so we can have a Navigator2 implementation for users to choose from which turns out to have been a lot more work than expected. My time is a little locked up on that now in preparation for the new Flutter Web Series.

I think having that setup and me hardening some of the tests we can definitely do that.

One question is how does it choose the version number? I don't know much about the system.

[buehler]

Hey @FilledStacks

Happy to explain :-)

Semantic Versioning clearly states what needs to happen for the version number to change. They also support preview / release candidate / whatever you name it - releases (e.g. v1.0.0-prerelease.1). Most packaging systems adhere to this standard since it makes updating pretty easy. All non breaking changes (i.e. a major version increase) must be compatible.

That said, semantic release makes use of that and removes the "human factor" in choosing an updated version number. I encountered the flaw myself when I needed to release a new version and was thinking about "is it really this or that?". Semantic release uses the Angular Conventional Commits standard to determine the next version number for the release. The three main parts of determining the new numbers are:

• fix ... -> create a new patch version
• feat ... -> create a new minor version
• Any commit with BREAKING CHANGE: ... in it -> create a new major version

Examples:

• fix(cli): fixed a bug
• fix: fixed a bug
• feat(generator): added error handling

• fix: made something un-nullable
  
  BREAKING CHANGE: this breaks the function and
  people need to migrate by using this and that.
  

The rest of the format can be reviewed in the aforementioned link to the conventional commits.

We've been using this system for several years now and it makes releasing such a breeze. Adhering to this format not only allows you to select version numbers, but also automatically generates changelogs and release notes. You can review this in almost all of our smartive repositories.

That said, a possible setup for stacked could be:

Since mono-repos are not particularly well supported, split all the packages into separate repositories.

This allows renovate bot (or dependabot...) to update dependencies in your packages one by one. So, if something in the core changes, all dependent packages get updated after the release as well.

Use semantic release in all the sub packages, and if needed create a "master" repo that links to all other packages with git submodules (to have all the packages in one place).

With that, all packages can be updated/developed on their own and are released when there are dependency-changes (renovate bot), or fixes/features/breaking changes. Nearly everything can be automated since you already have a premium stock of tests.

The only two things you'd need for the automation would be:

• A personal access token of the user that deploys the package
• The pub.dev credentials to actually deploy the package

I just created another automatically released package yesterday: https://github.com/smartive/flutter-generic-dropdown-widget which automatically releases with semantic release.

I'd be happy to help you with the setup if you require assistance ;-)

I hope I explained it in an understandable way

[FilledStacks]

@buehler thank you very much! I have setup the Stacked-Org and invited you. I appreciate your time and effort you're about to put in.

[buehler]

Perfect, just accepted the invite :-)
Can you make me an owner? (At least for the duration of the setup)
Otherwise I cannot setup some parts.

[FilledStacks]

Done! 🚀

[buehler]

Alright, so far so good.
I created and configured all the necessary basics. (The org does not use any pro features, so I downgraded to free again, it is all open source).

Now I'm going to move the code from the original stacked repo to the org repos and setup the tags and stuff for automatic deployment.

When this is done, the last step would be to create/update the PAT and the pub dev credentials and move this repository to the org under the name "framework". Reason being that you don't lose any stars and/or issues.

Then this repository (new "framework") will be repurposed to the "master" repository that contains submodules to all repositories in the org and is mainly used for development purposes and issue / discussion management. Effective merging and stuff is done in the repositories.

[FilledStacks]

This is awesome @buehler I received many notifications over the weekend so I knew you were making a lot of progress. This is really cool! We can go through the required updates later on our call. I'd like to keep the name stacked for the repo if possible instead of changing it to framework.

[buehler]

as far as I know, there are also github actions which check if the commit message is adhering to conventional commits.

[buehler]

Just came to my mind: another version of the automatic deployment, if you don't what to split the repository: leave all packages in one big mono-repo, but then, when something gets merged, ALL packages get deployed with the new version (e.g. https://github.com/buehler/dotnet-operator-sdk). So, all packages stick to the same versioning.

There are pro's and con's to both versions. Personally I'd stick with the separated repos and the one master repo that uses submodules for development / testing the interaction between the packages.

[FilledStacks]

@buehler the repo split is one of my concerns. But we can probably still do everything as it is now using a master repo and the sub modules. It's quite a lot of work 😅 I don't know if the effort will out weigh the reward at this stage.

Could also be that I just finished a massive amount of navigator 2 work in preparation for the new Flutter Web series and just want to start building the damn Flutter web app haha.

What do you think is the time / effort involved in setting this up?

[buehler]

The reason for the master repo would just be local development. From there you could create branches in each repo and develop a specific feature in one specific repo. In conjunction with my reply above: you could use this "master" repo to gather issues and discussions together.

And I totally understand the thing about navigator2 and your flutter app ;-)

I think splitting and setting up everything would take maybe, half a day?
As I said, I'd happy to help you if you need assistance :-)

As mentioned above, I would setup an organization, create all repos in there, create the master/issues repo with all packages as submodules to ease issue/discussion/development management, then setup renovate bot for all of the repositories and move the current packages in their own respective repos with automated testing/releasing in place.

[FilledStacks]

@buehler the cli package is not auto publishing the version.

When I look at the release logs it doesn't pick up that there are required changes. The commits start with feat or fix but it doesn't pick it up. I'll do a manual release for now because I need the version live to complete my tutorial.

[buehler]

Ofcourse you can just stay in main/master and just commit your stuff there. Then you can go for a commit per feature. Then you have everything in the changelog when you push it.

[buehler]

then you'll be able to do that ;)
create 3 commits like:

• feat: new
• fix: bug 1
• fix: bug 2

and create these in your main branch, then everything will get released at once (when you push)

[FilledStacks]

Interesting... but then we're taking out the PR workflow completely. Which is also fine I guess.

I think re-base might help with this. I'll allow rebased on the branches and see.

This will replay all the commits on main without duplication and should pick up the same as you mentioned above even when commiting on a different branch.

[buehler]

Yea, rebase & merge can also help. Then you just need to pay attention to the "proper" committing rules. All commits, that somehow (by any means) end up in the main branch and adhere to the angular commit format are picked up. We usually use squash & merge because we use the one branch for one topic strategy. How you manage the repository is totally up to you :)

[FilledStacks]

Awesome. I think I'll do rebase so the change log per version can have more than one change.