yarn replace

accepted/0000-yarn-replace.md

@@ -0,0 +1,62 @@
+- Start Date: 2018-08-23
+- RFC PR: (leave this empty)
+- Yarn Issue: (leave this empty)
+
+# Summary
+
+Add new subcommand, `yarn replace`, which removes one package and adds one package in one go.
+
+# Motivation
+
+Often, developers find themselves in situations where they try out one package just to find that the package is not useful for them and they want to try another package instead.
+
+Currently, the workflow for this is to execute `yarn remove <old-package>` and `yarn add <new-package>` sequentially. By having to execute two commands, native packages recompilation and other redundant tasks have to be executed twice, resulting in a timewaste.
+
+I believe `yarn remove <old-package> && yarn add <new-package>` is something that developers do commonly. Having a shorthand for these types of operation would also save time for typing.
+
+# Detailed design
+
+I propose a new subcommand called `replace <old-package> <new-package>`.  
+For example: `yarn replace leftpad left-pad`.
+
+The flow for this command is like this:
+
+- Check if <old-package> is installed, throw error if not
+- Check if <new-package> exists in registry, throw error if not
+- Remove <old-package> and generate a temporary lockfile that should be identical to one that would be generated by `yarn remove <old-package>`. Don't rebuild native dependencies in this step.
+– Execute `preinstall` lifecycle if needed.
+- Install <old-package> and transform the temporary lockfile into a new lockfile that should be identical to one that would be generated by `yarn remove <old-package> && yarn add <new-package>`. Save the lockfile. Execute `postinstall` lifecycle if needed.
+
+
+## Flags
+
+The supported flags for `yarn add` and `yarn remove` are the same, execept `yarn add` has these flags: `--ignore-workspace-root-check`, `--dev`, `--peer`, `--optional`, `--exact`, `--tilde`.
+
+`yarn replace` should honor all flags that `yarn add` honors. If the flag is supported by `yarn remove` as well, it should also be applied to the package removal section of the process. Otherwise, the flag just gets applied to the package installation process instead.
+
+# How We Teach This
+
+`yarn replace` is a convienience command for advanced users and is not a core feature of yarn.
+I see this feature in a similar category as `yarn upgrade-interactive`, a command that is not essential, but is nice to have.
+
+As this command is optional to use for developers, it is not necessary to teach novice users this command. However, advanced users who would like to get efficient when using Yarn, can read up on this command in the documentation
+
+
+# Drawbacks
+
+- It increases the amount of complexity of the Yarn project
+- It increases how much code needs to be maintained
+- Future additions to `yarn add` / `yarn remove` API might not make sense in a `yarn replace` context.
+
+# Alternatives
+
+N/A
+
+# Unresolved questions
+
+Which parts of `yarn remove` and `yarn add` are exactly 
+dant? I can think of:
+– Bootup of Yarn
+– Writing of Lockfile
+– Writing of package.json
+– Rebuilding of dependencies.