RFC: Add npm diff

accepted/0000-npm-diff.md

@@ -0,0 +1,60 @@
+# npm diff
+
+## Summary
+
+Add a new command that enables diff workflows (similar to `git diff`) for packages published in the registry.
+
+## Motivation
+
+- Complements `npm audit` and `npm outdated` workflows by providing insight on what changed across different package versions
+- Enables package authors to diff packlist-tracked-only file changes prior to publishing a new version of a package
+
+## Detailed Explanation
+
+Introduce a new `npm diff` command that will fetch tarball contents for two different versions of a module and print that output in an usable format to users.
+
+### npm diff `<spec>`
+
+Using a single `<spec>` allows users to retrieve diff output between an existing valid version of a package with the same **name** found in the actual dependency tree and the exact `<spec>` match from the registry.
+
+<img alt="Demo showing npm diff pkg in a repo with an actual tree installed" src="https://ruyadorno.github.io/svg-demos/npm-diff/npm-diff-yargs.svg" />
+
+### npm diff `<spec-a>` `<spec-b>`
+
+Fetches tarball contents of two versions of a package, represented by `<spec-a>` and `<spec-b>` and prints diff output.
+
+<img alt="Demo showing npm diff pkg in a repo with an actual tree installed" src="https://ruyadorno.github.io/svg-demos/npm-diff/npm-diff-simple-output.svg" />
+
+### npm diff --changelog
+
+Filter to only show CHANGELOG changes, makes the command more useful for printing content of larger packages.
+
+<img alt="Demo showing npm diff pkg in a repo with an actual tree installed" src="https://ruyadorno.github.io/svg-demos/npm-diff/npm-diff-changelog.svg?update=1" />
+
+### npm diff (no arguments)
+
+Meant as a helper tool to package authors, prints diff output between the current fs (tracked by packlist) and the last published version of that package.
+
+<img alt="Demo showing npm diff pkg in a repo with an actual tree installed" src="https://ruyadorno.github.io/svg-demos/npm-diff/npm-diff-no-args.svg?foo=bar" />
+
+## Rationale
+
+- A very common workflow is using npm outdated to figure out what dependencies need update and then manually reviewing what changed in between the current version you have in your project and whatever you can update to. That workflow involves multiple steps, some of them being extra mental hurdle (such as keeping track of the semver versions change and their meaning) some other very manual such as jumping around to repos, scanning through changelogs, veryfing semver contract is respected, etc.
+- Given the very long tail of packages published in the registry, a vast majority of packages sit somewhere below the 100LOC or a single function or whatever other measurement unit to define the pattern of very specialized and small packages adopted by the JavaScript ecosystem (speaking from personal experience here but maybe we can get some numbers to validate this assumption in case this is a contentious statement) - thus being perfect candidates to a simple review of the diff patches between versions.
+- It feels very natural to have a `npm diff` from the point of view of a heavy user of `git diff`s - It does provide much more quick insight on code that makes its way into our projects in a ([medium](https://en.wikipedia.org/wiki/Diff#Unified_format)) that most developers are already familiar with.
+
+## Alternatives
+
+- Leave the problem to userland and not ship a native `npm diff` command
+
+## Implementation
+
+Simply fetches two different tarballs from the registry (or reads from current fs if only comparing current version) and run a simple diff of each file, providing an usable output for users to work with.
+
+## Prior Art
+
+- https://github.com/juliangruber/npm-diff
+- https://github.com/g-harel/npmfs
+- https://github.com/FormidableLabs/publish-diff
+- https://github.com/sergcen/npm-package-diff
+