From 9cde5804278a0ca1c3425bb422b4ed089a7c46d2 Mon Sep 17 00:00:00 2001 From: seanmakesgames Date: Mon, 6 Nov 2023 09:21:52 -0800 Subject: [PATCH 1/3] Draft Upgrade Policy & Process Fixes #35 --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index eb68143b..0ef663f2 100644 --- a/README.md +++ b/README.md @@ -19,3 +19,35 @@ 1. Run `pnpm start` in the root directory 1. Navigate to the URL specified in the console or allow the browser to open it automatically - e.g. `[SUCCESS] Docusaurus website is running at: ` + +## Dependency Upgrades + +Our projects depend on many pre-existing and separately maintained packages. These packages are regularly updated for security issues, features, and other issues. + +### Policy & Values + +1. We regularly update our packages to make sure that our individual changes are small. This makes debugging and review easier. +1. We don't update major version changes in packages before they are 'out of beta' or had 'enough bake time'. +1. We optimistically take compatible versions as they are available. +1. We rely on tools and test automation wherever possible to reduce the cost on the team for package updates. +1. We use team judgment, validate our assumptions with others and make exceptions to our policy where appropriate. +1. We document any upgrade specific decisions in the created issue for that upgrade. + +### Upgrade Process + +This upgrade process is written for a major version upgrade with breaking changes which directly have impact on our project. This process is based on [the webpack major version upgrade guide](https://webpack.js.org/migrate/5/). The process can be remixed and composed to handle any size and sets of dependency upgrades. For simpler upgrades, only do the steps which are applicable. All PRs should be the smallest possible and maintain the release-ability of the production branch. + +1. Identify any specific guides for the major version upgrade. Follow them if available +1. If we are upgrading multiple major versions, we do them in sequence one at a time +1. Identify any required dependent loaders, plugins or package version requirements, run the upgrade process for them +1. Create `topic branch` +1. Upgrade package to latest version with the same major version. (compatible semver) +1. Fix all build warnings and deprecations +1. Migrate any compatible build flags +1. Run tests and turn on any 'major version mode' compatability testing flags during testing (revert before merge) +1. Create PR on `topic branch` and merge with standard process +1. Create new `topic branch` +1. Upgrade package to next major version +1. Clean up and migrate any incompatible build flags +1. Create PR on new `topic branch` and merge with standard process + From 238aa8bb6aa479251fadc420f05e99f67df92677 Mon Sep 17 00:00:00 2001 From: seanmakesgames Date: Mon, 6 Nov 2023 17:51:40 +0000 Subject: [PATCH 2/3] lintfix --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 0ef663f2..04a6dddc 100644 --- a/README.md +++ b/README.md @@ -50,4 +50,3 @@ This upgrade process is written for a major version upgrade with breaking change 1. Upgrade package to next major version 1. Clean up and migrate any incompatible build flags 1. Create PR on new `topic branch` and merge with standard process - From 9b05b51dd6776fc0e5b39e03f7ed6c4f1c18c07c Mon Sep 17 00:00:00 2001 From: seanmakesgames Date: Mon, 6 Nov 2023 23:38:07 -0800 Subject: [PATCH 3/3] upgrade policy updates --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 04a6dddc..ae9fc9de 100644 --- a/README.md +++ b/README.md @@ -27,11 +27,12 @@ Our projects depend on many pre-existing and separately maintained packages. The ### Policy & Values 1. We regularly update our packages to make sure that our individual changes are small. This makes debugging and review easier. -1. We don't update major version changes in packages before they are 'out of beta' or had 'enough bake time'. 1. We optimistically take compatible versions as they are available. +1. We update major version changes in packages when they are 'out of beta' and had 'enough bake time'. +1. We create issues for major version upgrades. Issues are not needed for other upgrades. +1. We document any upgrade specific decisions in the created issue for that upgrade. 1. We rely on tools and test automation wherever possible to reduce the cost on the team for package updates. 1. We use team judgment, validate our assumptions with others and make exceptions to our policy where appropriate. -1. We document any upgrade specific decisions in the created issue for that upgrade. ### Upgrade Process