Add migration guide and temporary warnings

doc/plugins.md

@@ -16,9 +16,17 @@ See [tools built with remark »](https://github.com/wooorm/remark/blob/master/do
 * [Using plugins](#using-plugins)
 * [Creating plugins](#creating-plugins)
 * [Publishing plugins](#publishing-plugins)
+* [Renaming from mdast to remark](#renaming-from-mdast-to-remark)
 
 ## List of Plugins
 
+> :warning: **mdast is currently being renamed to remark** :warning:
+>
+> All plug-ins prefixed with `remark-` are guaranteed to work.
+> Plug-ins prefixed with `mdast-` might as well, but without warrantees.
+>
+> (Are you a plug-in author? See [below](#renaming-from-mdast-to-remark))
+
 * [ben-eb/mdast-autolink-headings](https://github.com/ben-eb/mdast-autolink-headings)
  — Automatically add GitHub style links to headings;
 
@@ -161,3 +169,26 @@ This will also make a package usable by [Duo](https://github.com/duojs/duo).
 
 When publishing a plugin, you should utilize the package manager’s keywords
 functionality and include `"remark"` in the list.
+
+## Renaming from _mdast_ to _remark_
+
+First of all, thanks for taking the time to work with me on this. 👍
+I definitely value the time you put into the name-change. A lot.
+
+Here are some tips for the change:
+
+* I suggest upping to a new major release, released with the new name. In
+ the case of `mdast-foo@1.2.1`, that would go to `remark-foo@2.0.0`.
+ That updated version should depend and work with, as it name suggests,
+ **remark**.
+
+* Then, create a near-empty project with a `readme.md` (pointing to to
+ `remark-html` on GitHub or npm), and a deprecation notice, and publish it
+ as `mdast-foo@2.0.0` (yes, a major bump too).
+
+* Use `npm deprecate mdast-foo@2.0.0 'Renamed to`remark-foo`'`, with
+ some additional information if needed.
+
+That would ensure no users get any deprecation notices normally, but if they
+are in the process of updating their dependencies, they’ll get one and
+hopefully rename their dependency. 😄

readme.md

@@ -2,6 +2,15 @@
 
 [![Build Status](https://img.shields.io/travis/wooorm/remark.svg)](https://travis-ci.org/wooorm/remark) [![Coverage Status](https://img.shields.io/codecov/c/github/wooorm/remark.svg)](https://codecov.io/github/wooorm/remark) [![Inline docs](https://img.shields.io/badge/docs-A-brightgreen.svg)](http://inch-ci.org/github/wooorm/remark)
 
+> :warning:
+>
+> **remark** recently underwent quite some changes.
+> For one, it’s named changed from **mdast**. This means all the plug-ins
+> in the ecosystem need to change names too, which may result in some turbulence
+> the coming weeks (but most of the dust has already settled).
+>
+> [Read more about what changed and how to migrate »](https://github.com/wooorm/remark/releases/tag/3.0.0)
+
 **remark** is a markdown processor powered by plugins. Lots of tests. Node,
 io.js, and the browser. 100% coverage.