add changesets and documentation

[silesky]

changeset docs: https://github.com/changesets/changesets#documentation

TLDR: When developing a feature/bug/chore, run yarn changeset in your branch and commit the generated artifacts. When it’s time to release, merge the automatically created Version Package PR. This will kick off the release process, which results in the CI triggering yarn release to push tags to GitHub / publish packages to NPM.

Why publishing pipelines are extra complicated in a monorepo…
- How do you ensure the package you're releasing is also released in sync with all of its dependencies? If analytics-browser and analytics-node depend on analytics-core, everytime analytics-core is updated, we need to ensure that analytics-browser and analytics-node are also updated.
- You can no longer easily look at the commit history and see what should package or packages that commit affects. Even knowing what file it touched is not enough — if I update a file in core, I need to release core as a potentially major release and also, all packages that depend on core might need to released as minor releases.
- Generating a changelog is also annoying, it means figuring out which recent commits affect a specific packages and collecting them (manually) -/ there could be a lot of noise.
- Tools like semantic release and changeset force the user to create some kind of metadata in their PRs so the system can easily map each merge to its relevant package or packages, and can calculate the appropriate bump.

Changeset upsides (over lerna with conventional commits)

• way easier to fix if a non-standard commit gets onto master; does not heavily require annoying precommit hooks or magic tags like “feature” — you can run this at the beginning and not worry about commit messages the rest of the time
• user can have multiple commits and they can still all be squashed by GitHub without a user having to conform to the semantic release format.
• Does not rely on a user having to squash all of their commits very carefully / break them up into special selected tags
• Can be created at any time (during a PR would be ideal)
• PR automatically opens via GitHub

Changesets release bot:

Version packages example:

[changeset-bot]

⚠️ No Changeset found

Latest commit: a0b3a63

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[chrisradek]

I like this method of generating changelogs!

A question and a suggestion.

Q: What does the final changelog look like? It's at the repo root not per package right?

Suggestion: Can you update the PR template to also include instructions to generate a changeset?

[chrisradek]

Does this actually need to be a patch update? There aren't any user-facing changes - just contributor changes right?

[silesky]

Correct; technically it's just for demonstration purposes (to trigger the PR bot). I was going to delete the changeset after it was merged or after the PR is approved.

https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md#not-every-change-requires-a-changeset

[silesky]

Q: What does the final changelog look like?

The final changelog is here, and gets automatically updated by the bot whenever a new PR is merged in: #511 (BTW, you can do yarn changeset version to generate the changelog at any time on your local. I've added instructions here.

This changelog can be edited before its merged in, if needed. If a changeset is edited in any PR, the PR will automatically update to reflect the latest changelog according to master.

It's at the repo root not per package right?

It's per package (e.g. browser/changelog.md, node/changelog.md).

Suggestion: Can you update the PR template to also include instructions to generate a changeset?

Sure, I can update the PR template to suggest that user's run yarn changeset if you think that's useful.

[chrisradek]

Love that we'll have a changelog now versus combing through release notes!

[pooyaj]

amazing 💥

[pooyaj]

🙌

[pooyaj]

just for my curiosity ... what does this do?

[silesky]

I stole this pattern in another repo, but I don't remember which one https://github.com/facebook/jest/blob/main/package.json#L172

It should allow us to have fixed version numbers in our packages for the sake of publishing, but when developing locally or running tests, this resolutions key will always guarantee that both our dependencies and any transient dependencies will use the "current" workspace, rather than (accidentally?) using the version that is published (or maybe not-yet published) to npm. For example, if we have a not-yet-published @segment/utils that is updated, and is a transient dependency of @segment/analytics-core that is installed in @segment/analytics-node. If I'm running tests on analytics-node and it has a fixed version of analytics-core, will it pick up on the local changes to utils when we run our tests or do a build? I could be wrong, but I don't think so.