Reimplement changesets as a core command group

[paularmstrong]

Problem:

The changesets plugin relies on changesets, a third-party open source tool. While it exposes various packages that can be used within other tools, it is not primarily designed to do so.

There are also various issues:

• Changelogs are written to private packages Changelogs are written to private packages #313
• Building and applying release plans is cumbersome with changesets, but would be much easier with the oneRepo Graph object
• Source Dependencies are one of the main reasons oneRepo was created, as other monorepo tooling doesn't enforce or help with setting up and managing correct linking. Keeping changesets as a plugin makes this too optional and confusing to explain and implement.
• Need to init Jiti runtime interpreter within commands that use changesets packages because they have not fixed ESM vs CJS issues: fix(changesets): jiti for add & version #573
• People forget to write changesets, which can prevent versioning & publishing

Solution:

• Re-imagine and re-implement changesets as a core command group.
• Automate setting up and managing source-dependency settings vs published module settings
• Simplify the changeset workflow
• Include git changes without changesets in helping determine whether a Workspace is publishable

Design details

Entry-point

• one change
• Alias for one changeet, one changeets

one change add

• Should be the default command for one change

Changeset files

Changeset files should be added to the Workspace they are related to. This requires that any changeset that spans multiple Workspaces be duplicated to each Workspace.

The third-party changesets package writes to a root directory for all changes with a single file per change (regardless of the number of Workspaces they affect). This is generally fine, except when you have a distributed team working on many different projects, potentially unrelated. It also requires adding the changeset files to an ignore list when determining the affected graph for any given commit/pr.

By duplicating changeset within each Workspace, we have a clearer birds-eye view of the affected Workspaces without needing to run any scripts, as well as allow special rules per Workspace when adding/modifying and requiring changeset entries. Furthermore, this prevents requiring that two modules sharing a changeset be versioned at the same time, when those two modules may not actually share a dependency tree.

Example:

In the event that a change affects both carrot and raddish, we will write the same file in each Workspace's .changes/ directory:

- modules/
  - carrot/
    - .changes/
      - 1-foobar.md
  - radish/
    - .changes/
      - 1-foobar.md

File details

Filename

${number}-${hash}.md

The filenames shall be composed of a number and hash of the contents, separated by a dash (-).

The number will be determined as a 0-based incremental index against the other files within each Workspace's individual .changes directory. This allows developers to quickly determine order of changes when reviewing, before versioning & publishing.

It is explicitly okay if two change entries have the same index. This is helpful in understanding potential parallel work done across changes.

The hash value will be determined via the initial hash of the contents written to the file. The hash does not need to stay up to date and is only used as an initial way to create uniqueness of filename quickly.

Example:

---
type: minor
related:
  - other
---

<!-- markdown content here -->

Frontmatter:

what	type	description
type	'patch' | 'minor' | 'major'	Semantic version release type
related	Array<string>	Workspace names that share the same entry content

Modifying change entries

Change entries may be modified manually at any time. Validity will be determined at version time.

one change migrate

• Migrates .changeset files to oneRepo changes

one change pre

• Alias for one change prerelease, one change pre-release
• Accepts OTP input as prompt
• Determines new semantic version identically to one change version
• Queries against appropriately configured registry to determine pre-release incremental ID
• Global configuration for version suffix. Default pre
  • example: 1.0.0-pre.0, 1.0.0-pre.1, 1.0.0-pre.2
• Writes new version numbers to every package.json for both the version string in each Workspace as well as the dependencies and devDependencies versions.
• peerDependencies versions will be verified for overlap
• Exit behavior
  • default: Resets all package.json before exit
  • option: leave modifications intact

one change version

• Alias for one change up
• Accepts Workspaces input. If no input, presents a list of viable Workspaces.
• Always includes input Workspace dependencies.
• config option: includeGitLogs
  • If false, warns about dependencies with git log entries but no change entries since last version. Prompts for okay (bypass with -y)
  • If true, will present git logs without change entries for each Workspace and prompt for semantic version increment type.
• Lists all Workspaces with newly determined versions. Prompts for okay (bypass with -y)
• Writes to changelog files
  • Configurable with global options
  • Can write to multiple locations for each Workspace
  • Each location can indicate writeSafe mode
• Writes new version numbers to every package.json for both the version string in each Workspace as well as the dependencies and devDependencies versions.
• peerDependencies versions will be verified for overlap

one change publish

• Does not accept Workspace input
• Checks against appropriately configured registry to determine which Workspaces should be published
• Publishes each Workspace
• Accepts OTP input as prompt

Determining version-able Workspaces

1. Glob for .changes/*.md in each workspace. If there are files, mark it versionable and continue to next workspace.

2. If there are not change files, get the SHA from the last time the "version": "${workspace.version}" was modified

   git log -S '"version": "…"' -n 1 --format=format:%H -- path/to/package.json

   If there were git logs modifying anything in each workspace since its version modification SHA, it should be considered available for versioning.

Alternative lookup methods

1. When versioning, store the current SHA
   This could be problematic in repositories where merge-commits and history modification may be allowed.

[paularmstrong]

This work has been done in #582 and merged. It may not be complete and there may be some bugs. Consumers should utilize @onerepo/plugin-changesets until stable 1.0.0 release.