Auto-generate next version number when publishing NuGet packages (OSOE-400)

[Piedone]

In the publish-nuget action, optionally auto-generate the next version number for the following scenarios:

• Next major version (i.e. x.0.0).
• Next minor version (i.e. 1.x.0).
• Next patch version (i.e. 1.0.x).
• Next alpha version corresponding to an issue key (also taking care of alpha version indexing).

Manually added and USE_GITHUB_REF_NAME-generated version numbers should remain supported.

Perhaps, this could be achieved still with tags: You push the vnext-major tag, the action removes that tag and adds one with the next major version generated. Or, we could use manually triggered workflows. Detecting an issue branch vs dev could also trigger a behavior to publish an alpha version suffixed with the issue key in the branch.

Publishes with a manually added version tag should remain an option. The version tags should also still be there in the repository, since we need those for tracking and correlating commits with GitHub releases.

Jira issue

[BenedekFarkas]

I'd recommend suffixing the marker tag with (at least) the issue code to avoid potential collisions, e.g., vnext-major-osoe-400.

[Piedone]

Related: #220

Ideally, the version number would be fully auto-generated, but I don't think it's possible to automatically decide between a minor and patch version (since that depends on whether the changes contain new features or only bugfixes), only whether it's a major version since it includes breaking changes.

[BenedekFarkas]

The best I can think of now is that an issue/PR can be labelled (to manually indicate what kind of changes are in the PR), so the workflow could use that information, but that information should also propagate somehow to default branch builds.

[Piedone]

Yeah, that's the original idea, I just added a note with some further thoughts.

[Piedone]

This is especially interesting if you're doing a lot of releases at once, like us releasing all of our Orchard Core-related projects during an OC upgrade. So, how about doing something for all projects at once too?

I'm thinking about something like having a release manifest file in the OSOCE root, that defines the following:

• Which projects to release.
• What should be the version bump for all of them.

Then, an automation would go through all the projects, starting at the bottom of the dependency graph, and take care of all releases:

1. Release the current project.
2. Update all of its references in other projects.
3. Release the next project.
4. Update references...

Basically, automating https://lombiq.atlassian.net/wiki/spaces/DEV/pages/786857987/Managing+releases+of+open-source+projects#An-example-of-releasing-OSOCE-projects

This might need to be something like a local script though, that utilizes the feature under this issue.

[BenedekFarkas]

FYI https://github.com/GitTools/GitVersion (some of our clients use it already).

[Piedone]

I have a hard time understanding what that tool does. It seems it manages the .NET version metadata, and I think it somehow can also determine the next version to use, but even after combing through the docs, I don't see how it does it and what happens once it determines a version number.

[AydinE]

See: Lombiq/Open-Source-Orchard-Core-Extensions#787

I've been thinking a bit on this issue and decided to go with a set of 3 local scripts versus creating a github action. I actually started with an action at first but then found out that it was too limiting and working with a 'marker tag' like for example vnext-major would also not be a good option because deleting a tag is quite strange sometimes and tags have to be unique.

What it is now is a set of scripts that can and will call each other with the right input but don't have to and can also be used standalone.

The first script Vnext is what was initially described in this issue. A script that determines the next version.
It takes an argument to determine what type of version increment (major, minor, patch or pre-release)

Some examples:

.\VNext.ps1 -path .\src\Libraries\Lombiq.HelpfulLibraries\ -type "major" -commitChanges $true

This would determine the version number for a new major release of HelpfulLibraries, create the tag and push it out. Because of the -commitChanges $true flag, it will also now do some extra things, which is where the other 2 scripts come in.

• First it will determine which projects are part of the HelpfulLibraries release, because this will up the version for all of the projects that fall under this solution. Now that we have that information we will scan the entire solution and look at each and every .csproj file to see if there is a package reference to one of these projects. If so we update the version and save the file.

The changes for updating the version will not automatically be committed this should be a manual action, also we'd need to wait for the Nuget package to be pushed and available.

.\VNext.ps1 -path .\src\Libraries\Lombiq.HelpfulLibraries\ -prerelease $True -issue "OSOE-1234"

This would create a pre-release, in this case we don't have to set the -type flag but we do have to set an -issue so that we can properly tag it. We are also ommiting the -commitChanges $true because in this case we are probably only wanting to test it out in a specific project.

This describes most of the main features but I'd create more thorough documentation for it later.

Would love to get your thoughts and input on this

[Piedone]

Sounds interesting!

I lost you after "which is where the other 2 scripts come in." though. What do you mean by "this will up the version for all of the projects that fall under this solution"?

Or to put it otherwise, after you release HL with VNext, the next steps are (following the wiki:

1. Wait for the NuGet package to be available on nuget.org.
2. Update all projects in the solution using HL to reference the new version. This includes the UI Testing Toolbox (UITT).
3. Release UITT with VNext.
4. Wait for the NuGet package to be available on nuget.org.
5. Update all projects in the solution using UITT to reference the new version.
6. Release Helpful Extensions with VNext...

Do these scripts do/will do something on steps 1-2 and 4-5?

[AydinE]

Do these scripts do/will do something on steps 1-2 and 4-5?

It does in a way,
It actually does step 2 first, when given the -commitChanges $True flag. But you will have to manually do step 1. which is to actually wait before pushing the changes. (and have a chance to review them)

Once done you repeat the same process for UITT.

So the proces would look like this:

1. Run .\VNext.ps1 -path .\src\Libraries\Lombiq.HelpfulLibraries\ -type "major" -commitChanges $true
   (This created the version tag + pushes it to Github so running this script will start the NuGet build action)
   (It will also update all project references to the new version because of the -commitChanges $true flag)
2. Review changes made by script in terms of project references an versions. And wait for NuGet build to finish.
3. Once NuGet finishes, and changes have been manually commited do the same thing for UITT.

UITT

1. Run .\VNext.ps1 -path .\test\Lombiq.UITestingToolbox\ -type "major" -commitChanges $true
2. Review changes made by script in terms of project references an versions. And wait for NuGet build to finish.
3. Once NuGet finishes, and changes have been manually commited do the same thing for Helpful Extensions.

Helpful Extension

1. Run .\VNext.ps1 -path .\src\Modules\Lombiq.HelpfulExtensions\ -type "major" -commitChanges $true
2. Review changes made by script in terms of project references an versions. And wait for NuGet build to finish.
3. Once NuGet finishes, and changes have been manually commited do the same thing for Helpful Extensions.

Continue if needed.

[Piedone]

I see, great! Though with -commitChanges $true I'd expect it to git commit the changes to the submodules, or why did you name it as such (as opposed to e.g. -UpdateReferences)? (BTW switches, since they correspond to parameters, are better CamelCased in PS).

@Psichorex @sarahelsaig you did a lot of recursive releases lately, please check this and see how much it would've helped your workflow.

[AydinE]

I see, great! Though with -commitChanges $true I'd expect it to git commit the changes to the submodules, or why did you name it as such (as opposed to e.g. -UpdateReferences)? (BTW switches, since they correspond to parameters, are better CamelCased in PS).

Agreed, initially I was planning to also make it commit the changes but I thought having the option to review it and just make a commit yourself makes more sense and is more flexible. Will change the naming

[Piedone]

OK!

[AydinE]

I have made some changes to this, what makes most sense in terms of where to write the documentation for how to use these scripts. In a readme within the solution or on confluence or something else entirely?

[Piedone]

Most of it in a Readme, but link from and change the wiki page accordingly too.

[AydinE]

Added a Releasing.md file that outlines what/how to use the scripts.

Added a link to it in the wiki

Added an extra Interactive flag that defaults to true, this prevents the script from automatically pushing a git tag to remote but rather asks the user first.

[Piedone]

This was done for OSOCE in Lombiq/Open-Source-Orchard-Core-Extensions#787.