github-desktop/docs/contributing/upgrading-dependencies.md

# Upgrading Dependencies

This document outlines how we manage the dependencies that GitHub Desktop needs,
as some need to be handled differently to others

## General Guidelines

In the interest of stability and caution we tend to stay a version (or more) behind on our most critical dependencies. We vary whether this is a major, minor, or patch version depending on the development practices of the dependency's project.

| Dependency  | Versions Behind Latest |
| --- | --- |
| electron | >= 1 major |
| electron-packager | >= 1 major |
| electron-winstaller | >= 1 minor |
| typescript | >= 1 minor |
| codemirror | >= 1 minor |
| react | >= 1 minor |
| react-dom | >= 1 minor |
| keytar | >= 1 minor |

## The Impact Of A Dependency

We group the dependencies in `package.json` and `app/package.json` into three
buckets, based on their value to the project and what happens when a bad upgrade
occurs.

Because of the nature of the Node ecosystem, changes upgrading between versions
of a package can introduce subtle changes that need to be reviewed and vetted.
We also have finite engineering resources on the project, so we're a bit choosy
with how and when we choose to upgrade dependencies, and some dependencies might
be very stale for a very long period of time.

The measured impact of a dependency can be identified by answering these three
questions, and some examples of answers here will help with the next section.

### How is this dependency used in the project?

  - Core dependencies like Electron, React and Typescript are critical to
    Desktop - without these dependencies we'd have a very different product
  - Application dependencies are other external packages which are needed at
    runtime - how can we test they still work as expected?
  - Tooling dependencies help to build and verify Desktop works as expected, but
    aren't shipped to users

### If we ship a bad update due to updating a dependency, what is the impact to users?

  - If a core dependency is broken, it may cause the app to crash, lose the
    user's work, or require the user to reinstall an old version of Desktop to
    get back to a usable state
  - An application dependency breaking may affect some user's workflows and
    their ability to work
  - Broken tooling impacts the developers and their ability to work on the
    project, and potentially affects shipping builds to users, but otherwise
    might not be seen

### Can we leverage automation to verify a change is safe?

  - Core dependencies need to be tested in a variety of setups due to their
    complexity, and may still require manual testing in some cases even with
    automated tests in place
  - Application dependencies may be able to be wrapped in tests, to help
    identify regressions before a change is released to users
  - Tooling dependencies are used heavily as part of continuous integration
    tests, and any potential problems will be caught early

## Grouping dependencies by impact

With the criteria above, we can group dependencies into these three buckets that
help guide when they should be updated.

### Core dependencies

These are the most important dependencies to the app, and include:

 - `package.json`
   - `@types/node`
   - `electron`
   - `electron-packager`
   - `electron-winstaller`
   - `typescript`
   - `webpack` and related dependencies
 - `app/package.json`
   - `codemirror`
   - `dugite`
   - `react`
   - `react-dom`
   - `keytar`

Anyone who wants to get involved with updating these versions should be very
familiar with both the library and what has changed between versions, so the
review process is focused on verifying the impact of the change rather than
understanding what has changed.

The maintainers have significant experience with these dependencies, and may
wish to upgrade one of these dependencies at a later time than when a
contribution is opened by the community.

### Application dependencies

This group of dependencies represent the rest of the listed dependencies in
`app/package.json` - there are lots of small dependencies which are approachable
for external contributions.

If you are interested in upgrading one of these, take a look at where it is
used in the application and confirm that the affected functionality works as
expected before opening a pull request.

### Tooling dependencies

The remaining dependencies in `package.json` are used to help build, test and
verify Desktop, and are covered by a strong suite of tests which our CI
infrastructure will run.

External contributors who have some familiarity with the libraries that we use
are encouraged to contribute, but please ensure that PRs focus on upgrading a
specific set of dependencies - this will make reviews easier to perform.

## DefinitelyTyped dependencies

We need to specifically call out the `@types/*` dependencies in `package.json`
because those are typically updated when a related package is updated.

These are the rough rules for handling `@types/*` dependency updates, using
`keytar` as an example as it has a corresponding type declaration package
`@types/keytar`:

 - if you are upgrading `keytar`, ensure that you also upgrade `@types/keytar`
   and that any code affected by the type declarations change is also updated
 - if there is no `keytar` upgrade but a new version of `@types/keytar` is
   available, this suggests that some declarations have been updated - ensure
   that the app code works fine with it

Not all libraries will have a corresponding `@types/` dependency, but as we use
TypeScript heavily in the codebase we want to ensure we're working against the
latest declarations of the untyped JS that we consume.