add 0000-yarn-upgrade-interactive-transitive.md

Author: magicmark

text/0000-yarn-upgrade-interactive-transitive.md

@@ -0,0 +1,54 @@
+- Start Date: 2017-03-18
+- RFC PR: (leave this empty)
+- Yarn Issue: (leave this empty)
+
+# Summary
+
+This RFC proposes the addition of a "--transitive" flag to `yarn upgrade-dependencies`.
+
+This will allow developers to choose from and 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
+
+*** (I am still scoping this out; any help here would be appreciated!) ***
+
+TODO
+
+# How We Teach This
+
+The Yarn CLI should add a `--transitive` to the output of `yarn upgrade-interactive --help`, explaining that this will list all dependencies, including transitive dependencies in the list.
+
+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 uses this term (http://blog.npmjs.org/post/145724408060/dealing-with-problematic-dependencies-in-a).
+
+The new feature:
+- is a relatively minor addition of functionality; the documentation will need amending to describe the new flag.
+- 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 these situations 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 regenerated, the presumably critical information of the minimum version of the transitive dependency could be lost.
+
+# Alternatives
+
+Users could continue to update transitive dependencies via the 'regular' workflow.
+
+TODO
+
+# Unresolved questions
+
+Is there a possibility of introducing transitive dependency version conflicts that cannot be resolved?
+
+TODO