pnpm and changesets

[mistermoe]

Changes

Switched from npm -> pnpm

Note

learn about pnpm here.

Motivations behind the switch

better support for multi-package repos.

---

pnpm prevents phantom dependencies. A "phantom dependency" occurs when a project uses a package that is not defined in its package.json file.

how do these occur? When installing dependencies with npm, all packages are hoisted to the root of the modules directory. As a result, source code has access to dependencies that are not added as dependencies to the project which means you can import something that you haven't included as a dependency in package.json

By default, pnpm uses symlinks to add only the direct dependencies of the project into the root of the modules directory

---

Human readable lock files. package-lock.json merge conflicts feel like an impossible battle to win. pnpm-lock.yaml is far easier to read (at least imo)

---

pnpm includes a command (pnpm licenses list) that can be used to list all licenses used by all dependencies. this is especially helpful when building open source libraries

---

the above aren't even the primary motivations behind why other projects are switching. if you're interested in those you can read about them here

Introduced changesets

Note

learn about changesets here.

managing the versions of all 3 packages in this repo by hand was getting supa cumbersome and eagerly waiting for the opportunity to ruin someone's day.

Decided to give changesets a shot to handle version management for us! i've configured changesets to do fixed versioning. This means that packages will be version-bumped and published together even when there are no changes done to some of the member packages.

Given that:

• http-server depends on http-client and protocol
• http-client depends on protocol

any changes to protocol or http-client would end up version bumping all 3 packages anyway.

I've also installed the changesets bot into this repo. It'll comment on PRs saying that either:

• a changeset might need to added (note that PRs changing things like documentation generally don't need a changeset)
• say that the PR is good and already has a changeset.

Remaining TODOs

• setting up changesets github action
• adding docs to README explaining how to use changesets manually

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2773c2f

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

[michaelneale]

Have used it for a while with dev site and it was fine there so +1 from me

[jiyoontbd]

are these files under .changeset/ supposed to have odd names?

[KendallWeihe]

Okay I think I understand how this works...

• The bot can detect if an update is needed
  • It can comment on the PR to remind the developer know to do their duty
  • Also, somehow it can detect patch/minor/major??? Which I'd be very curious to understand how it is able to detect that
• Then you run pnpm changeset
  • This automatically generates these funnily-named markdown files
  • I think there's a parallel here to staging a commit using git add prior to the actual commit
• Then you run pnpm changeset version
  • This actually executes the version update
  • Which, appends the changeset to the relevant CHANGELOG.md files
  • Updates the version in the relevant package.json files
  • And lastly, deletes the funnily-named changeset files

So the point is, these funnily-named files are ephemeral, and only exist in between the changeset (again, akin to "staging" a commit using git add) and changeset version (which executes the changeset update)

[KendallWeihe]

Okay, and so I think the idea of the GitHub Action is...

1. As developers open PRs, the changeset bot will comment reminding them to update the version
2. So then they'll run pnpm changeset
3. This will create a new funnily-named markdown file
4. Then they will merge their PR (without running changeset version -- meaning, all those funnily-named markdown files will be merged into main)
5. At which point, the GitHub Action will automatically open a new Pull Request
6. This new PR will automatically run the changeset version such that the package.json files & the CHANGELOG.md files are updated
7. Then, let's say a second developer comes in with a new PR and merges it into main
8. That PR which the GitHub Action previously opened (from step 5) will automatically re-run the changeset version to pull in the new changes
9. At some point in the future, the team is ready for a new release, at which point, they simply merge the open PR

[KendallWeihe]

So to sum up, developers stage their changesets on each PR, and the GitHub Action automates the execution of the changeset & the resulting release

[KendallWeihe]

Nice, yeah this looks solid AF. The description is well thought-out too, so thank you for that 👍

I'm slightly sus that an automated changebot is something we'll want, but won't know for sure until we get further into the experience

[mistermoe]

Re: changebot

Agreed! Very interested to see how it plays out.

Oh yeah, as an alternative to figuring out CI in this PR, we can just run pnpm changeset version to have changeset version bump everything based on the two changesets present. Then, commit / push the outcome of running that.

Let's us tackle CI stuff in a separate PR.

Down with either route!

[KendallWeihe]

Manually executed changeset version, created new issues for the two remaining TODOs

• Add changesets GitHub Action #31
• Add guide for changesets to README doc #32

Going ahead and merging this and will do the other two things in follow-up PR(s)

[KendallWeihe]

What is CI: true doing here?

[KendallWeihe]

Interesting, I see it here https://pnpm.io/using-changesets

I also see explicit execution of pnpm config set store-dir $PNPM_CACHE_FOLDER which we aren't doing in our jobs