Updating dependencies

Here's what to do when preparing a dep update PR.

1. Run yarn outdated to get a list of dependencies with updates.

2. For each available update, open the URL displayed in the list and look for the CHANGELOG file, the Releases tab in Github, or whatever may be available that lists changes since the installed version. Failing availability of any clear list, read the descriptions of the commits between the versions in question.

3. Make sure to pay attention to any deps where the versions listed as "Wanted" and "Latest" don't match. These will likely have some major or breaking changes. There are also a few special cases, see below for a list.

4. Run yarn upgrade-interactive --latest and select all the packages that don't list major breaking changes (unless you want to fix those breaking changes as part of your PR). The --latest flag causes yarn to upgrade the version specified in the package.json, not just in the lockfile, which is useful as an easy source of record. However, it also causes yarn to upgrade directly to the latest version and ignore the version range specified in the package.json, so if you don't want to go all the way to latest, it's easier to just edit the package.json directly and then run yarn install.

5. npx yarn-deduplicate; yarn install will simplify the sub-dependency tree to use the latest version of a package that satisfies all of their version range requirements, rather than keeping any number of old versions around. This is unlikely to introduce a problem in itself, although it's possible. It's purpose is to keep our sub-dependency tree as clean (and small) as reasonably possible.

6. TEST TEST TEST. Find all the places in the codebase where we use the package, and test those components. Test manually locally, and then pay attention to the automatic integration tests when you push your branch. If the changes for a given package are just minor bugfixes, you generally won't have problems, but sometimes issues sneak through and introduce new bugs, so we should always verify.

7. Before you merge, make sure there isn't a workshop ongoing or a similar release protection window.

---

Special case packages

These are all in the root package.json; the integration-tests package is free of special cases.

• react, react-dom, react-test-renderer

  • These need to be the same version. For react-dom, however, we use a version that adds hot reload, which isn't updated as frequently, so that limits us. At some point in the future, react-refresh will be available as a rewire plugin to use instead (and someday hopefully will be built in to react-scripts), so we won't have this limitation anymore, hopefully.

• react-scripts

  • This underpins our whole app; it manages builds and local development. Even minor changes to this package can have major effects (that's why it's pinned to the exact version rather than a range, which is unique among our direct dependencies), so make sure to test extra hard.

• marked, react-simplemde-editor (because it specifies its own version of marked)

  • We're avoiding updating these until we figure out how to handle the changes in output sanitization that newer versions bring, without breaking the current behavior on how html entities are rendered in e.g. workspace descriptions.

• path-to-regexp

  • This governs how all of our links and url's are generated, and major updates can break existing links without us noticing very easily. This needs some dedicated examination, understanding, and testing to verify that not only do internally generated links continue to work, the url's they point to are the same as before.

• react-hyperscript-helpers

  • Version 2.0.0 doesn't add any new features, but it removes the Typescript definitions (which are, admittedly, sometimes incorrect). However, this causes IntelliJ to complain a lot more about things being incorrect, so we're not upgrading until there are new types to avoid a lot of meaningless underlines.