New release process

[olaf-k]

A short breakdown of what #954 means for us as Vivid developers.

tl;dr:

• Releases: not everything merged on main is published.
• Deploying pure documentation changes is a separate process.
• The title of your PR matters.

📦 Releases

When a PR is merged on main, release-please will run and do two things:

1. Check whether it is a component change. It does so simply by checking that at least one modified file is under libs/components.
2. If it is, it will then update—or create if one doesn't exist yet—its own release PR, refreshing the list of changes since the last release and bumping the version in accordance to semantic changes.
   That's it!

Now, when we want to actually publish our changes, we'll have to merge the PR release-please created and updated. This will go through the following steps:

1. Create a GitHub release: the code is tagged and the release list of changes is documented on Vivid's GitHub page.
2. /libs/components/CHANGELOG.md is updated with the same list of changes and the version in libs/components/package.json is updated.
3. The components library is built and published to npm.
4. The documentation application is built and deployed to production on Deno.

📃 Documentation deployment

As stated above, the process focuses on releasing the Vivid components. But what if we need to update the documentation site independently of any component release?

This can be done on a case-by-case basis by running the Deploy Deno action manually:

👓 PR titles

The title of your PR at the time of merging on main will determine the content of the changelog and the next release version number.

The conventional commit format required by release-please is similar to the SemVer we were using. It follows the familiar <type><scope>: <description> format we already know and adds the ability to signal breaking changes with a ! mark. You can read the short page about the format and see practical examples here.

To make sure the PR titles are formatted correctly, the title linter that runs on every commit has been updated. Note that the <scope> part is mandatory for Vivid commits.

[yinonov]

Create a GitHub release: the code is tagged and the release list of changes is documented on Vivid's GitHub page.

you mean the release page?

[olaf-k]

both actually. there will be a release page indeed but I was thinking of the badge (on the homepage, in the right margin) at the time of writing

[olaf-k]

Some TODOs with varying degrees of importance:

• CONTRIBUTING.md should be updated with relevant info from this page.
• The creation of the release PR does not trigger the pull-request workflow. This is by design and quite fine since it doesn't push code, but it leaves the PR in a pending state because some checks are mandatory. How should we handle that?
  
• The potential double deployment issue (components + doc) should ideally not happen but it'd be nice to prevent it at workflow level. The current syntax to exclude paths does not allow that unfortunately, so we'd have to resort to using another solution.