Add initial proposal for yarn upgrade-transitive

Author: magicmark

text/0000-yarn-update-transitive.md

@@ -0,0 +1,89 @@
+*   Start Date: 2017-03-18
+*   RFC PR: (leave this empty)
+*   Yarn Issue: (leave this empty)
+
+# Summary
+
+This RFC proposes the addition of a "upgrade-transitive" command to the Yarn CLI.
+
+This will allow developers to upgrade transitive dependencies listed in the yarn.lock file.
+
+# Motivation
+
+It is occasionally necessary to upgrade versions of transitive dependencies in an application (in the case of security patches or critical bug fixes) without going through the regular workflow. Currently, to upgrade transitive dependencies, a developer would have to hand edit the yarn.lock file (which is an anti-pattern; reasons as to why this must not be done are outside the scope of this RFC).
+
+Consider the dependency graph A->B->C. (A is an application that lists B in its package.json; B lists C in its package.json.) The regular workflow would be to bump the minimum required version of C in B, and bump the new minimum required version of B in A.
+
+This causes friction however when B is not already at the latest version in A, and is sufficiently large that upgrading to a new version of B in A is non-trivial.
+
+By allowing the upgrading of transitive dependencies listed in the lockfile, bug fixes and security patches can be rolled out quicker.
+
+# Detailed design
+
+TODO: (tl;dr - I think this will just be a wrapper around [Selective dependency resolutions](https://yarnpkg.com/lang/en/docs/selective-version-resolutions/#toc-why-would-you-want-to-do-this) - more on this below!)
+
+# How We Teach This
+
+The Yarn CLI should add a `upgrade-transitive` to the output of `--help` commands, explaining that this will allow developers to pass in the name/path to a dependency that should be updated.
+
+Yarn should use the term "transitive" to describe the sub-dependencies as this is a mathematically accurate description, and more precise than "sub-dependencies" or "additional dependencies". (npm also uses this term (http://blog.npmjs.org/post/145724408060/dealing-with-problematic-dependencies-in-a).
+
+The new feature:
+
+*   is an addition of non-trivial functionality. the documentation will need amending to describe the new command.
+*   is backwards compatible, does not change other existing functionality of Yarn, and would not require existing users to change their workflow in any way.
+*   should be taught via release notes and a blog post at time of release. The documentation and `--help` output will serve as a reference for future users.
+
+# Drawbacks
+
+It is preferred to handle upgrades of transitive dependencies via the "regular workflow" as described in the motivation section above. Introducing this as an additional workflow could confuse or engender bad practices. The documentation of the flag should be written with care to reduce this as a possibility.
+
+If the yarn.lock file has to be completely regenerated, the presumably critical information of the minimum version of the transitive dependency could be lost. (This behaviour of regenerating lockfiles is not unprecedented https://github.com/yarnpkg/yarn/pull/3544)
+
+# Alternatives
+
+## "Hacky" workarounds
+
+If the version of the desired transitive dependency is within range as declared by its parent, one can manually trigger yarn to re-resolve this information by re-adding the parent dependency through existing CLI APIs.
+
+## Existing Alternatives
+
+If the version of the desired transitive dependency is _not_ within range as declared by its parent, users can wait for the parent to release a new version which includes the new transitive dependency.
+This release cycle may slow down the release of critical fixes.
+
+## `resolutions` field
+
+Users could manually edit `package.json` to target the new version of the desired transitive dependency.
+
+https://yarnpkg.com/lang/en/docs/selective-version-resolutions/
+
+# Other APIs
+
+*   As proposed in https://github.com/yarnpkg/yarn/issues/2394, `yarn upgrade --deep`
+
+# Unresolved questions
+
+*   Is there a possibility of introducing transitive dependency version conflicts that cannot be resolved?
+*   What happends when a new version of a transitive dependency introduces a new dependency?
+
+## Should there be a `--force` option to allow transitive dependencies to be bumped past their regular semver range?
+
+This may be desirable in the case of critical bugfixes/security patches. There is already prior art for yarn to override semver ranges, with the introduction of the `resolutions` field (https://yarnpkg.com/lang/en/docs/selective-version-resolutions/).
+
+## Where should the new resolution information live?
+
+### A) Add to the resolutions field
+
+This would make this new API essentially be a UI wrapper around the existing `resolutions` field.
+
+### B) "Nowhere" - just update `yarn.lock`/`node_modules`
+
+This would do the work of updating the transitive dependency, and save it only in the `yarn.lock` file.
+
+#### Pros of Option A
+
+Option A has some advantages over option B:
+
+*   The override information is persisted outside yarn.lock, which as discussed above is volatile. If we're having to use this command, we probably want to make sure the override information doesn't get lost.
+*   The override information is more clearly expressed, and visible to humans (makes it harder to forget about)
+*   This builds on work already within yarn [created for this purpose](https://yarnpkg.com/lang/en/docs/selective-version-resolutions/#toc-why-would-you-want-to-do-this).