Versioning multiple release branches

[arabold]

Hello! Let me first thank you for this action as it has been a tremendous help in the last half year we've been using it.

Our branching strategy, however, is somewhat special:

• main - this is the main branch which will automatically be deployed to our development environment. Any push in this version will increase the "MINOR" version number automatically, v1.1.0, v1.2.0, v1.3.0, etc.
• release/customer-a - to release a version for a specific customer ("Customer A") we merge the main branch into a dedicated release branch. For this branch we want to increment the "PATCH" version: v1.2.1, v1.2.2, v1.2.3, etc. based on the original version v1.2.0 that was in merged from the main branch. However, incrementing the PATCH version isn't critical, but would be helpful.
• release/customer-b - the same is true for a second customer. Only the patch version should increment.
• release/customer-c - and the third one and so forth...

For a single customer release branch this works perfectly fine. We create a git tag for every version we create. However, you can probably already see the issue: customer-a could have a version v1.2.1 and the release for customer-b could be based on the same version from main, also resulting in a v1.2.1. This will lead to a conflict in the git tag and an error.

My first idea would be to use namespaces to solve this. Each customer would get its own namespace. But that leads to the versioning scheme being completely independent between customers, which we don't want either. I want to know that v1.2.x is deployed for both customer A and customer B. I don't wont completely independent version numbers.

True, this seems like a somewhat convoluted concept and maybe you're right... But it is what I'm stuck with right now. Any ideas or suggestions how this could be solved? If I could add some kind of identifier, i.e. the customer ID, to the tag name it would avoid conflicts. But if I simply use namespaces the version count starts with zero for each release branch/each customer, which is not desired.

[PaulHatch]

Hey @arabold, great to hear that, thanks.

I can't really say without knowing what other rules you have in place, but I can share a few thoughts and especially experiences related to implementing the version from branch feature. As you are probably familiar, the version from branch feature allows you to take either the major or major+minor version from the branch name, and ignores any tags which do not match it, using only tags which start with the same major or major and minor version as the branch name ends with. This does sound a bit similar to what you are trying to do. I spent quite a long time before implementing this trying to figure out a way to do purely branch based versioning, but could not come up with a solution. I finally realized it was not possible, and the reason for this is that branches move. There is not a stable commit associated with a branch the way there is with tags, nor a way to determine what path a branch has taken.

If you are able to include the version with the branch name (e.g. customer-a/v1.2, this may be a possibility, but it sounds like you want to change the version for a customer over time. I have considered adding a feature that would allow the values used for major and minor to be injected as inputs to the action, something like this might be useful here, although you'd then need to store the version somewhere else.

Keep in mind too, that this action is merely providing information, you are free to do whatever you want with it and there's nothing that says you can't call the increment the minor version, ignore or override any value you wish, run the action multiple times, etc.

[arabold]

Thanks for the feedback. I was thinking about possible solutions for the last 4 days, but I think my preferred feature would be to allow custom formatting of the version (tag). Currently the action uses a simple regular expression to find the latest tags. This expression is more or less hardcoded. If I use a prefix or a namespace, that is simply added to the regex to limit the search space.

What I'm suggesting is the following:

1. In addition to ${major}, ${minor}, ${patch} and ${increment} we could introduce ${shortsha} to allow the 8 character GIT sha to be part of the version. I think that's helpful in any case and for me it would solve the conflicting Git tags.
2. It would require the regex to become a bit more flexible, i.e. instead of just hardcoding it we could write a parser/regex builder that converts the format string "${major}.${minor}.${patch}.${shortsha}" into a regex dynamically: ([0-9]+)\.([0-9]+)\.([0-9])\.([a-f0-9]{8}). The regex builder would essentially replace the placeholders with expressions to build the final regex matcher, i.e. ${major} becomes ([0-9]+).
3. The regex builder would even eliminate the need for prefix and namespaces as these could be part of the format string instead:

   version_format = "v${major}.${minor}.${patch}-bar"

   The regex builder would turn this into something like this: /^foo-([0-9]+)\.([0-9]+)\.([0-9])\.([a-f0-9]{8})-bar$/i. That regex is then used for searching git tags as well as parsing the git tag into major, minor, patch again. We could use named capturing groups internally to make the parsing a lot easier (i.e. (?<major>[0-9]+)).

With a logic like this we would get a lot more flexibility on how the version is formatted while potentially simplifying the options (remove tag prefix, namespace, namespace separator). Or, if we keep those params, the regex builder would simply need to support parsing them and this would be the default version format: ${prefix}${major}.${minor}.${patch}+${increment}${namespace}.

[arabold]

Code is sometimes more helpful to explain the idea:

type PlaceholderMapping = Record<string, string>;

const placeholderRegexPatterns: PlaceholderMapping = {
  '${major}': '(?<major>[0-9]+)',
  '${minor}': '(?<minor>[0-9]+)',
  '${patch}': '(?<patch>[0-9]+)',
  '${shortsha}': '(?<shortsha>[0-9a-fA-F]{7})',
};

/** Function to escape all characters in a string that could be interpreted as special regex characters. */
function escapeRegexCharacters(str: string): string {
  return str.replace(/[$.*+?^{}()|[\]\\]/g, '\\$&');
}

/** This function replaces placeholders with their regex patterns and escapes other parts of the string. */
function generateRegex(input: string): string {
  // First, escape all special regex characters in the input string
  let escapedString = escapeRegexCharacters(input);

  // Then, replace the escaped placeholder patterns with their regex patterns
  Object.entries(placeholderRegexPatterns).forEach(([placeholder, regex]) => {
    // Create a new RegExp object for the placeholder, escaping special characters
    // Double escape as we're matching against an already escaped string
    const placeholderRegex = new RegExp(escapeRegexCharacters(escapeRegexCharacters(placeholder)), 'g');

    // Check for duplicate placeholders
    if ((escapedString.match(placeholderRegex) || []).length > 1) {
      throw new Error(`Placeholder ${placeholder} appears multiple times.`);
    }

    // Replace the placeholder in the escaped string with its regex pattern
    escapedString = escapedString.replace(placeholderRegex, regex);
  });

  return escapedString;
}

// Example usage
const inputString = 'foo-${major}.${minor}.${patch}-bar';
const regexString = generateRegex(inputString);
console.log(regexString);
// This should output: foo-(?<major>[0-9]+)\.(?<minor>[0-9]+)\.(?<patch>[0-9]+)-\$bar

Now, this regex can be used to match version strings in the Git tags or anywhere else. The regex parser will correctly split the string into major, minor and patch. At the same time it is very flexible and allows you to build your string exactly the way you want.

[PaulHatch]

I've read this a few times and I'm afraid I am still not following. This is a change to the action?

[arabold]

Yeah, let me take a step back. What I'm proposing is a new feature for the action to allow custom Git tag formats.

Today, even though the PaulHatch/semantic-version action doesn't actively tag any Git commits, it relies on a predefined pattern to identify the latest version in previously tagged commits. It expects Git tags to follow the common v<major>.<minor>.<patch> pattern with optional prefix, suffix and increment.

While this is sufficient in many cases, some use cases demand more flexibility in how the version string is constructed. In my particular case I want to add either the deployment environment, branch name or the commit SHA to the version to avoid potential conflicting Git tags. For example, I would like a naming scheme like this being possible in future:

gitGraph
  commit tag: "v1.0.0"
  commit tag: "v1.1.0"
  branch foo
  commit tag: "v1.1.1-foo"
  commit tag: "v1.1.2-foo"
  commit tag: "v1.1.3-foo"
  checkout main
  commit tag: "v1.2.0"
  branch bar
  commit tag: "v1.2.1-bar"
  checkout main
  checkout foo
  merge main tag: "v1.2.1-foo"
  checkout main
  commit tag: "v1.3.0"
  commit tag: "v1.4.0"
  checkout foo
  merge main tag: "v1.4.1-foo"

Loading

The foo and bar suffix in this example are not distinct namespaces that would each start versioning from zero but part of the version name (and git tag) itself.

In other words, I'm suggesting to allow custom Git tag formats that are fully configurable by the user. Today, the DefaultTagFormatter supports a prefix (i.e. v) and an optional namespace. But otherwise limits the tag to the three components <major>.<minor>.<patch>. Allowing custom formats would give more flexibility about how Git tags should be named. In addition, it would allow the addition of new components such as the commit sha or even the current date/time as part of the Git tag.

Hope that clears it up a bit. I realized I already jumped to conclusions without even caring to explain my train of thought 🤷