Add solution about pre-releases on non-standard branches

[dottxado]

Please check if the PR fulfills these requirements

• The commit message follows our guidelines
• Tests for the changes have been added (for bug fixes/features)
• Docs have been added/updated (for bug fixes/features)

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)
Feature

What is the current behavior? (You can also link to an open issue here)

What is the new behavior (if this is a feature change)?
Add the possibility to -built branches to be included in the automatic release process without generating invalid tag names for Composer

Does this PR introduce a breaking change? (What changes might users need to make in their application due to this PR?)
No

Other information:

[tyrann0us]

According to this search, the value of BUILT_BRANCH_SUFFIX is always -built. So, while it is configurable in theory, we don't use other values. (It might make sense to make this a boolean USE_BUILT_BRANCH or similar with hardcoded value, but that's another topic.)

This makes me wonder whether we could put the tagFormat change in the release.config.js template, potentially saving users from maintaining this file in their repository if the only change is the tagFormat property:

tagFormat: "<%- version.replace('-built', '') %>"

This would make adding this note to the documentation superfluous (while we should add an explanatory comment to the config file). And for packages not using the built branch approach, no harm is done.
What do you think?
CC @shvlv

[dottxado]

I partially agree.
If we include this setting in our template, we should also include the -built branches, otherwise it is totally useless.

So the template should be modified like this:

module.exports = {
  "branches": [
    "main",
    "main-built",
    "next",
    "next-built",
    {
      "name": "beta",
      "prerelease": true
    },
   {
      "name": "beta-built",
      "prerelease": true
    },
    {
      "name": "alpha",
      "prerelease": true
    },
   {
      "name": "alpha-built",
      "prerelease": true
    }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    ["@semantic-release/npm", {
      "tarballDir": "release",
      "npmPublish": false
    }],
    ["@semantic-release/exec", {
      "prepareCmd": "[ -f index.php ] || [ -f style.css ] && sed -i \"s/Version:.*/Version:     ${nextRelease.version}/\" index.php style.css || true",
    }],
    "@semantic-release/github",
    ["@semantic-release/git", {
      "assets": ["CHANGELOG.md", "package-lock.json", "package.json", "composer.json", "style.css", "index.php"],
      "message": "chore(release): \${nextRelease.version} [skip ci]\n\n\${nextRelease.notes}"
    }]
  ],
  "preset": "angular",
  "tagFormat": "<%- version.replace('-built', '') %>"
}

For my team that uses frequently these two workflows in combination, this change would be awesome, because, as you said, we have to maintain a local copy only to add the -built branches.

[tyrann0us]

If we include this setting in our template, we should also include the -built branches, otherwise it is totally useless.

Yes, good point. I'm okay with extending the configuration file like this. Please note that it should be possible to use wildcards for branch names according to the documentation (https://github.com/semantic-release/semantic-release/blob/master/docs/usage/workflow-configuration.md#name), so you could do something like *-built (untested!).

@Chrico, are you okay with hardcoding a value (-built) that is actually configurable (but nobody uses a different value; see above)?

[dottxado]

I add another point about wildcard branches 😄 since Composer accepts only alpha, beta, RC and pl strings in the tag name, having a wildcard can spark the possibility of having a foo-built pre-release branch and resulting in a 1.0.0-foo.1 tag. Maybe if we want to enforce a working standard, having the branch listed can be a good way? 🤷‍♀️

[tyrann0us]

Thanks for incorporating all the changes. LGTM! 😉