[Big Chore] Multi versioning and automatic changelog generation

[art-alexeyenko]

• This PR follows the Contribution Guide
• Changelog updated
• Upgrade guide entry added

Description / Motivation

Introduction of the search package is throwing a wrench in our cozy versioning management, where one version described all. Future changes will throw more wrenches, so we need to support multi-versioning and independent package publish for our monorepo.

The How

New flow includes:

• changesets:
  • changelog management
  • release versioning
  • release prep
• lerna:
  • pre-release versioning
  • pre-release (canary) publish
  • release publish (changesets publish does not work well with dry run publishes into internal npm feed)
• Changeset versification in PRs:
  • Will be added via changeset-bot

The main (latest release) flow is the following:

1. Developer adds a change and must generate a changeset for their PR (there is a GitHub action to check this)
2. Developer PR still generates canary version - only for packages changed since last release (determined via release git tags - see step 5)
3. Once PR is merged, a release Pull Request is auto-created or auto-updated with new changes. It will contain the updated packages versions.
4. The release PR is prepared via a customized script called cascade-version. The logic is similar to changeset version, but all the base package version bumps will cascade over to dependendents. I.e. core@1.4.0 -> core@1.5.0 update will result in minor version change for react, nextjs and all the dependent packages.
   OOB changesets does not allow that.
5. Once release is decided, merge the release PR with [release] prefix in the commit. This will make CI to add relevant release Git tags and publish to NPM.

Patch/hotfix release flow:

1. Run hotfix-release-prep Github action
2. Input package and version that need to be patched or updated
   • This will allow the action to find the release tag associated with the release-to-be-patched
3. Action will check out the corresponding release tag and create a release/package@version branch for hotfix development
   • This will generateand publish new canary versions. hotfix.rc.canary tag will be attached to npm packages
4. Cherrypick/commit hotfix changes into release branch with corresponding changesets
   • This will auto-generate patch release PR
5. Merge patch release PR when ready

• This will trigger the release.

Changelogs

Changelogs will be generated automatically for every package for ease of tracking changes. The entries from base packages will be propagated to the dependents' changelogs.
The intended new usage for changelogs is to publish github releases only for the user-facing packages. At this time these are:

• @sitecore-content-sdk/nextjs
• @sitecore-content-sdk/search

We don't need to post individual changelogs for each package this way, ensuring changes are accounted for and GitHub spam is avoided.

Sample new changelog format:

1.9.2

Patch Changes

• [nextjs] [core] Core patch (commit)

1.9.1

Patch Changes

• [nextjs] [react] Patch React update (commit)

1.9.0

Minor Changes

• [nextjs] [react] Minor React feature (commit)

Samples versioning

create-content-sdk now has devDependencies to the packages used in its samples. When sample is scaffolded, package.json will be read for the appropriate versions (i.e. @sitecore-content-sdk@nextjs:1.4.0) which will be inserted into scaffolded sample.
In future we can keep samples as separate packages, simplifying create-content-sdk.

Testing Details

Lots of manual testing over at https://github.com/art-alexeyenko/content-sdk

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Chore - but a big one

[github-actions]

⚠️ Changeset Files Missing

@art-alexeyenko, no changeset files were found in this PR.

If this PR includes changes that should be released, please run the following command and commit the generated changeset file:

yarn changeset

You can continue with the merge if this is a chore PR that doesn't require a changelog entry.

[illiakovalenko]

The proposal looks better now 👍
Please find my comments below.

[illiakovalenko]

New analytics packages are missing

[illiakovalenko]

@art-alexeyenko @sitecore-content-sdk/personalize is missing

[art-alexeyenko]

Considering today's discussions, let's keep this convo open and I'll add the final list of packages before merging.

[illiakovalenko]

yeah, not urgent since it will be changed