Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Dependency Upgrade Policy #35

Closed
8 tasks done
Tracked by #34
tukib opened this issue Nov 3, 2023 · 1 comment · Fixed by #36
Closed
8 tasks done
Tracked by #34

Dependency Upgrade Policy #35

tukib opened this issue Nov 3, 2023 · 1 comment · Fixed by #36
Assignees

Comments

@tukib
Copy link
Member

tukib commented Nov 3, 2023

Problem

We do not have a policy for upgrading the dependencies we rely upon.

Goal

Our goal is to develop a policy that answers:

  • How do we propose and assess the need for a dependency upgrade?
  • How do we implement and review a dependency upgrade?

Tasks

  • Decide where this policy will be documented.
  • Document an assessment procedure:
    • Decide where upgrade assessments should be documented (e.g. PR, issue, project)
    • Identify required information for an upgrade decision
    • Define (or rule out) a measure for perceived importance and/or complexity
  • Document a review procedure:
    • Identify required information for implementation and review
    • Define a test plan really just standard review procedure, any strict definition can be done with workflow impl

Several items are out of scope for this issue, but have been acknowledged as potential future work:

  • Upgrade workflows and automation
  • Regular auditing of dependencies
  • Addressing implications of deferring/denying upgrades (e.g. security)
@tukib
Copy link
Member Author

tukib commented Nov 3, 2023

For upgrade assessments, I think the policy should provide a specific issue template. Generally if we are proposing an upgrade, we have some idea of the motivation. The issue description might start out with empty sections or TBDs, but this can be fleshed out as the upgrade is assessed. It also documents the proposal clearly without having to read through comments.

The assessment template could require:

  • upgrade motivation, categorise into:
    • hard requirements (e.g. security, it must be done or addressed in some other way)
    • specific advantages
    • non-specific benefit (e.g. preventing version drift)
  • version bumps for itself and related dependencies, whether we already meet them

NPM recommends Semantic Versioning1, so it might make sense to fast-track the assessment procedure if no major version bumps are necessary.

  • Major: provide some examples of breaking changes to determine how much work the upgrade would cause.
  • Minor/patch: if the work leading up to this did not unveil breaking changes, just skip this in the evaluation. If it does break, we should be catching it in the review process and we can backtrack.

As for the review procedure, I think this is pretty much just standard review workflow: open a PR, update dependencies, test with test plan, fix issues and repeat, then merge. I don't think we require any specific information for impl/review per say, but with #34 we may identify things that make sense to document. Docusaurus has provided guidance for a testing workflow2, which is essentially:

  • ensure site builds
  • identify visual regressions3

Footnotes

  1. NPM docs on SemVer About Semantic Versioning -

  2. Docusaurus workflow suggestion Upgrading frontend dependencies with confidence -

  3. ChatGPT on visual regressions Detecting Visual Regressions -

@tukib tukib self-assigned this Nov 3, 2023
seanmakesgames added a commit that referenced this issue Nov 6, 2023
seanmakesgames added a commit that referenced this issue Nov 8, 2023
* Draft Upgrade Policy & Process

Fixes #35

* lintfix

* upgrade policy updates
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant