Revised/Enhanced Branch Support

[PaulHatch]

In version 5.1.0 support branch-based versioning will be revisited, possibly multiple versioning strategies will be supported.

This ticket will serve to organize the design for this change, feedback and ideas are welcome.

[georg-eckert-zeiss]

That would be great. I just tried to use semantic-version to determine the SemVer on a support branch (support/2.3.5) and could not find a way to do it.

Best regards.

PS: Guess I took this wrong. It should automatically check that branch when choosing it for the workflow, right?

[PaulHatch]

For anyone interested in this, it would be helpful to share specifics of your use case.

Here is the behavior I'm considering now to be "default" branch behavior:

• Get the current branch (git rev-parse --abbrev-ref HEAD)
• Try to parse the version from that branch
• Check for tagged commits as normal
  • If a tagged commit is found that is higher, use that tag and the version from that tag
  • Else if no tagged commits are found, find the intersection of the branch with the master branch, using that commit in place of the tagged commit to calculate increment

From this point on the action would follow the normal flow as if the version and commit had been determined by a tag.

Here we'd consider only the branch that is currently checked out explicitly, and not attempt to do anything like the previous two iterations of behavior of discovering arbitrary branches. The reason for this is that branches can move, and without some explicit rules that you enforce on merging version branches it is not possible to determine the correct branch to use in a number of fairly common situations.

There is still a possibility of running into issues if you at some point merge a commit which is tagged for a later version into the version branch. To address this, I'm considering also including a mask, so that version tags on a branch would be excluded if they changed either the major or minor version number.

I think that this may be good enough to cover any supported use case without any additional branching strategies. If you are doing this today and interested into this feature, please share your feedback.

[arabold]

I'm trying to figure out if and how I could setup something like the following:

• I have main branch into which all engineers commit and push code. This gets deployed to the "development" environment.
• In addition I have a release branch into which code is merged from main only manually/on demand, i.e. if we want to do a new public release to the "production" environment.
• Any commits/merges to the main branch should automatically increment the minor version, i.e. v0.1.0, v0.2.0, v0.3.0, etc.
• Any commits/merges to the release branch should automatically increment the patch number, i.e. v0.3.1, v0.3.2, v0.3.3, etc.
• Assume I have v0.4.0 on main and v0.3.1 on release. Now I merge from main into release the new merge commit should be tagged v0.4.1 as it is based off the v0.4.0 from main.
• In the same scenario, I now create a hot-fix directly on the release branch that did not go into main first. I.e. the main branch could already be several versions ahead of the release branch. The new commit on the release branch should now be tagged v0.4.2 as that is the next version for that branch.

I want to use this version scheme for a SaaS product to track which version includes which JIRA tickets. I understand that this isn't strictly semver but the hypothesis is that any changes to main are usually warranting at least a minor version bump, while hot-fixes directly on release should never be a breaking change. If anything, they revert a "broken" deployment to a working state again.

Does this use case make sense to you and a) is this achievable with the current version of this action, b) if not then is this something to be considered for the next major update?

Update: Just answered my first question: Yes, that is possible with the current version and works pretty much out of the box by using different minor_pattern based on the branch that's building.

[PaulHatch]

Version 5.1.0 has just been released without this enhancement which was originally planned to be included. As mentioned above this needs some more definition, the edge cases are complicated and there needs to be some opinionated decisions made to resolve them. I have started and included a guide document which is planned to eventually describe a number of different branching/versioning modes and perhaps reference example projects. If you have a clear strategy working that you can contribute, it would be helpful to add it to this thread.

[PaulHatch]

After a lot of consideration I think that using branches alone is fundamentally unviable without greatly increasing the complexity of the configuration to the point it would probably not get used. Branch commits are not fixed to a specific commit and as such do not provide sufficient information to determine the version. For this feature, a new mode will be added that uses a combination of branch name and tag name.

The intended use case for branches is when you want to release a version of a product, but continue to provide ongoing releases to that version after the next major version is released. E.g. a product such as a desktop application where you may ship version v3.7.6 first, then v4.0.0, put continue to provide ongoing updates to the v3 version. If you are releasing something like a web application running only a single instance or mobile app where there is only a single timeline of releases and older versions do not get updated, you should stick to tags. I believe the vast majority of modern applications will not need this.

Having said that, the plan for this is as follows:

• The existing use_branches option will be deprecated.
• A new option, version_from_branch, will be added.

Setting the new option, the major and optionally minor version will be taken from the branch name, while the patch and minor (if not taken from the branch name) will continue to come from tags. Tags for versions that do not match the version taken from the branch name will be ignored.

For example, you create a new branch, release/v4 and at the same time tag this branch as v4.0.0. The action continues to version as usual, since the major version of the tag matches the branch name, you can go on to tag v4.0.1, v4.1.0, etc. If at some point in the future you merge a fix into the branch that includes a v5.0.0 tag, this will be ignored. The action will only ever produce tags which match the branch name. Additionally in this mode, "major" commits would be treated as "minor", similar to the prerelease mode already supported.

Similarly you could name the branch release/v4.1 and only tags of major version 4, minor version 1 would be considered, with all commits treated as patch so as not to exceed the version specified by the branch.

If version_from_branch is set to true, the branch name will look for a final numeric or pair of numeric values delimited by a ., but a custom regex could be supplied here as well.

[PaulHatch]

Available in v5.3.0, examples and further documentation to follow. In the meantime any feedback is welcome.