feature request: consider supporting a workflow to enable preview releases

[travi]

New feature motivation

the conversation in #2503 resulted in the realization that the true desire is support for an additional workflow beyond those currently officially supported by semantic-release. we've heard plenty of other requests for similar workflows in other previous threads as well.

while the officially supported pre-release workflow can be used in a way that can accomplish a similar outcome, it is worth noting that pre-releasing every release isn't the intended use of that officially supported workflow.

New feature description

verification for some projects requires testing beyond the scope of the ci pipeline of the project itself. some example use cases are described:

• by @dominykas: ERELEASEBRANCHES error when the main branch is used for pre-release #2503 (comment)
• by @hutchic: ERELEASEBRANCHES error when the main branch is used for pre-release #2503 (comment)
• Pre-Releases for Pull Requests #1433

our typical response to such requests is that semantic-release is opinionated in ways that strongly favor continuous integration and continuous deployment. part of being successful with those practices is isolating the project and having strong test coverage to ensure that the behaviors intended to be available from the public interface of the project are fulfilled before release or integration into consumers. a goal of this thread is to have a conversation about where that stance might miss real world needs and what accounting for that might mean for the semantic-release project

[travi]

The goal here is to pre-release without pushing a commit at all - sort of like CITGM. This is completely automated.

i really like this sort of description for this sort of workflow. calling it something like a canary helps distinguish this desire from the intended use of the existing pre-release workflow

[travi]

one question that i think needs to be clarified with the desired workflow here is how a pre-release/canary gets promoted to be a stable release. in the official pre-release workflow, the merge to the release branch accomplishes this goal. all releases before merge are pre-releases. merging to the release branch promotes to stable

in #2503 (comment), @hutchic mentions:

A human is required to trigger the GitHub Action workflow for a proper release, which uses a separate releaserc.json configuration to manage this process.

is something similar needed for the use case you describe @dominykas?

[travi]

our typical response to such requests is that semantic-release is opinionated in ways that strongly favor continuous integration and continuous deployment.

this comment from @hutchic is worth considering in this context:

My team is currently in the process of transitioning towards trunk-based development, but our organizational processes and practices are still evolving to fully support this paradigm. In our interim state, we have found it beneficial to conduct pre-releases for every commit to the trunk (main) branch, using the release branch workaround as a temporary solution.

[dominykas]

one question that i think needs to be clarified with the desired workflow here is how a pre-release/canary gets promoted to be a stable release. in the official pre-release workflow, the merge to the release branch accomplishes this goal. all releases before merge are pre-releases. merging to the release branch promotes to stable

In our use case, we specifically look to avoid creating PRs - right now, we're creating empty PRs solely to push out these pre-releases (tooling helps, but that's still a distraction).

We also do not necessarily want to "promote" these releases to stable per-se. We're creating a pre-release version of the App with a pre-release version of the Library. There will never be a release version of the App with the pre-release version of the Library - instead we'll at some point get a release version of the Library and then the App would pick that up in the next release (or in the next lock file update, if there is one).

I think there were some good examples of this in semantic-release itself fairly recently, with the migration to ESM? In that case, semantic-release itself had major changes, of course, but imagine that it hadn't - that the only changes were in, say, @semantic-release/npm which would have had something like vNext-beta.3. There would never be a semantic-release stable which uses a @semantic-release/npm@beta - we'd get a @semantic-release/npm@stable first.

A human is required to trigger the GitHub Action workflow for a proper release, which uses a separate releaserc.json configuration to manage this process.

is something similar needed for the use case you describe @dominykas?

In it's essence - yes, although we took a slightly different approach and we have a rather smart release.config.js which returns a different configuration after it inspects the environment.

[hpe-ykoehler]

Kind of curious, how can you release something without a commit? isn't your materials part of the project need to display version information? How can you change from a prerelease to an official release without a commit to change the internal code as to display the new version information for example, the changelog, etc.

We use a trunk-based approach as well, we have a devel branch which is an "alpha" pre-release and a mainline branch which is where official release are done. Everyone only works with the "devel" branch, when a release is required we trigger a different job/action, which then merge the devel to mainline and produce an official release.

I am not clear how is that different than what is being requested and I am curious to learn it.

We control that no one can commit to mainline directly without going thru our job/action.

[hutchic]

In my case there's nothing commited to the repository that displays version information so the difference between an official and a pre-release is the github release / tag name.

[hpe-ykoehler]

But semantic-release purpose is about modifying changelog, generating a new version, creating a tag, if you do the relaese without a commit, not all the plugin would work, then how do you manage that ? trying to tell people that if you use this workflow, plugins 1, 2 and 5 will not work?

[hutchic]

changelog on the github release page not commited. So yes in this case the changelog plugin wouldn't work

[hpe-ykoehler]

A review of all plugins would be required as to understand which one would or not work, for example, I think the license plugin would also then become incompatible https://github.com/cbhq/semantic-release-license based on its description, and maybe other plugin not track on the page.

In my case, when semantic-release does a commit, there are 2 files that are part of this commit, the first is the changelog which is due to my use of the changelog plugin, the second is a version file which is due to the use of the exec plugin. If I remove those, the commit would be empty, and therefore semantic-release would not do a commit, and instead just mark my last commit with a git tag no?

If semantic-release does an "empty" commit, in a situation where no files are changes, then I agree that this makes no sense, but I was under the impression that semantic-release doesn't require a git commit to occurs to make a release already and that it was based on the plugin usage you made in the commit was required or not.

[travi]

i plan to give this conversation attention again soon, but conversation about semantic-release requiring commits or not is off topic for this thread. semantic-release does not require commits as part of the release. you can choose to include commits as part of your release process by including the git plugin in your config, but we discourage this unless you understand the trade-offs.

please try to keep this conversation focused on the proposal for an additional workflow and open separate threads for other conversations

[matthewwolfe]

Use Case

I'll chime in with a flow that I would like to implement that fits in with this feature request. I would like to be able to have a library that every time I merge to the default branch (main), a canary version is created automatically, and I have the option to then manually create a regular production release from that.

The pipeline would look something like this for the main branch:

tests (automatic) -> publish canary (automatic) -> publish (manual)

This would allow me to continually merge to the default branch and stack a bunch of features, allow users of my library to see "coming soon" functionality to test out bugfixes before they are production released.

I had planned to implement the pipeline by having two separate release configs that would be specified by each job:

publish canary -> { name: 'main', prerelease: 'canary' }
publish -> { name: 'main', prerelease: false }

However, the publish canary causes an error stating that there must be at least one release branch, even though there will eventually be a release branch further down in the pipeline process.

Prior Art

I think of this workflow as a single branch "nightly" or "preview" setup. Canary for me will not be experimental code, it is merely pre-production code in the sense that it will all eventually be promoted to a regular release.

NextJS does releases like this. They regularly publish canary versions that all eventually end up as a production release https://github.com/vercel/next.js/releases

Other Considerations

Creating a separate "release" branch and then never using it -- This appeases semantic release but feels hacky when really I just want a way to not trigger ERELEASEBRANCHES and tell semantic release that I know what I am doing.

Having the publish canary job dynamically create a canary branch, publish there, and then delete the branch -- Again this feels hacky and unnecessarily complex when really I just want to tell semantic release that "Yes it is fine there isn't a release branch specified, just trust me and make a a canary release"