Add buffer deprecation migration guide

[fhinkel]

Add guide from https://github.com/ChALkeR/safer-buffer/blob/master/Porting-Buffer.md

Fixes: nodejs/node#19827
Refs: nodejs/node#19079

/cc @ChALkeR @addaleax @Trott

[Trott]

Nit: ESLint

[fhinkel]

Good catch. Done.

[Trott]

Nit: ESLint

[Trott]

Quick-read about-to-pack-for-a-flight LGTM!

[ghost]

LGTM

[LinusU]

I think that does 4 additional dependencies is actually smaller in size than safer-buffer, maybe it could be fair to promote all three approaches more equally, and having drawbacks for each listed...

note: I'm the author of buffer-from, etc. so I'm probably very biased here 😄

[Trott]

@LinusU Would you be willing to draft up proposed alternate text for this part?

[LinusU]

Actual size of node_modules folder as reported by du -sh node_modules:

safer-buffer                              60K
buffer-{alloc,alloc-unsafe,fill,from}     48K

[LinusU]

@Trott Sure thing!

Somebody should review it carefully so that I don't try to sell my own modules too much though 😄

[LinusU]

My proposal for the relevant part:

<a id="variant-2"></a>
## Variant 2: Use a polyfill

There are three different polyfills available:

- **[safer-buffer](https://www.npmjs.com/package/safer-buffer)** is a drop-in replacement for the
  entire `Buffer` API, that will _throw_ when using `new Buffer()`.

  You would take exactly the same steps as in [Variant 1](#variant-1), but with a polyfill
  `const Buffer = require('safer-buffer').Buffer` in all files where you use the new `Buffer` API.

  Make sure that you do not use old `new Buffer` API — in any files where the line above is added,
  using old `new Buffer()` API will _throw_. It will be easy to notice that in CI, though.

- **[buffer-from](https://www.npmjs.com/package/buffer-from) and/or
  [buffer-alloc](https://www.npmjs.com/package/buffer-alloc)** are
  [ponyfills](https://ponyfill.com/) for their respective part of the `Buffer` API. You only need
  to add the package(s) corresponding to the API you are using.

  You would import the module needed with an appropriate name, e.g.
  `const bufferFrom = require('buffer-from')` and then use that instead of the call to
  `new Buffer`, e.g. `new Buffer('test')` becomes `bufferFrom('test')`.

  A downside with this approach is slightly more code changes to migrate off them (as you would be
  using e.g. `Buffer.from` under a different name).

- **[safe-buffer](https://www.npmjs.com/package/safe-buffer)** is also a drop in replacement for
  the entire `Buffer` API, but using `new Buffer()` will still work as before.

  A downside to this approach is that it will allow you to also use the older `new Buffer()` API
  in your code, which is problematic since it can cause issues in your code, and will start
  emitting runtime deprecation warnings starting with Node.js 10
  ([read more here](https://github.com/chalker/safer-buffer#why-not-safe-buffer)).

Note that in either case, it is important that you also remove all calls to the old Buffer
API manually — just throwing in `safe-buffer` doesn't fix the problem by itself, it just provides
a polyfill for the new API. I have seen people doing that mistake.

Enabling ESLint rule [no-buffer-constructor](https://eslint.org/docs/rules/no-buffer-constructor)
or
[node/no-deprecated-api](https://github.com/mysticatea/eslint-plugin-node/blob/master/docs/rules/no-deprecated-api.md)
is recommended.

_Don't forget to drop the polyfill usage once you drop support for Node.js < 4.5.0._

Rendered:

[LinusU]

ping @Trott @fhinkel ☝️

[fhinkel]

Do you mind if we merge this as is and put your changes in a separate PR to make reviewing and attribution easier?

[LinusU]

Sunds good 👍

[fhinkel]

Thank you!

[LinusU]

Here it is :)

#1674

[Trott]

Is this style and structure difference intended?

@vsemozhetbyt Unintentional, I'm sure. PR to fix welcome. @nodejs/website

[fhinkel]

Not intended, thanks for noticing. I think I just fixed it.