+++ /dev/null
-# PostCSS Runner Guidelines
-
-A PostCSS runner is a tool that processes CSS through a user-defined list
-of plugins; for example, [`postcss-cli`] or [`gulp‑postcss`].
-These rules are mandatory for any such runners.
-
-For single-plugin tools, like [`gulp-autoprefixer`],
-these rules are not mandatory but are highly recommended.
-
-See also [ClojureWerkz’s recommendations] for open source projects.
-
-[ClojureWerkz’s recommendations]: http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/
-[`gulp-autoprefixer`]: https://github.com/sindresorhus/gulp-autoprefixer
-[`gulp‑postcss`]: https://github.com/w0rm/gulp-postcss
-[`postcss-cli`]: https://github.com/postcss/postcss-cli
-
-## 1. API
-
-### 1.1. Accept functions in plugin parameters
-
-If your runner uses a config file, it must be written in JavaScript, so that
-it can support plugins which accept a function, such as [`postcss-assets`]:
-
-```js
-module.exports = [
- require('postcss-assets')({
- cachebuster: function (file) {
- return fs.statSync(file).mtime.getTime().toString(16);
- }
- })
-];
-```
-
-[`postcss-assets`]: https://github.com/borodean/postcss-assets
-
-## 2. Processing
-
-### 2.1. Set `from` and `to` processing options
-
-To ensure that PostCSS generates source maps and displays better syntax errors,
-runners must specify the `from` and `to` options. If your runner does not handle
-writing to disk (for example, a gulp transform), you should set both options
-to point to the same file:
-
-```js
-processor.process({ from: file.path, to: file.path });
-```
-
-### 2.2. Use only the asynchronous API
-
-PostCSS runners must use only the asynchronous API.
-The synchronous API is provided only for debugging, is slower,
-and can’t work with asynchronous plugins.
-
-```js
-processor.process(opts).then(function (result) {
- // processing is finished
-});
-```
-
-### 2.3. Use only the public PostCSS API
-
-PostCSS runners must not rely on undocumented properties or methods,
-which may be subject to change in any minor release. The public API
-is described in [API docs].
-
-[API docs]: http://api.postcss.org/
-
-## 3. Output
-
-### 3.1. Don’t show JS stack for `CssSyntaxError`
-
-PostCSS runners must not show a stack trace for CSS syntax errors,
-as the runner can be used by developers who are not familiar with JavaScript.
-Instead, handle such errors gracefully:
-
-```js
-processor.process(opts).catch(function (error) {
- if ( error.name === 'CssSyntaxError' ) {
- process.stderr.write(error.message + error.showSourceCode());
- } else {
- throw error;
- }
-});
-```
-
-### 3.2. Display `result.warnings()`
-
-PostCSS runners must output warnings from `result.warnings()`:
-
-```js
-result.warnings().forEach(function (warn) {
- process.stderr.write(warn.toString());
-});
-```
-
-See also [postcss-log-warnings] and [postcss-messages] plugins.
-
-[postcss-log-warnings]: https://github.com/davidtheclark/postcss-log-warnings
-[postcss-messages]: https://github.com/postcss/postcss-messages
-
-### 3.3. Allow the user to write source maps to different files
-
-PostCSS by default will inline source maps in the generated file; however,
-PostCSS runners must provide an option to save the source map in a different
-file:
-
-```js
-if ( result.map ) {
- fs.writeFile(opts.to + '.map', result.map.toString());
-}
-```
-
-## 4. Documentation
-
-### 4.1. Document your runner in English
-
-PostCSS runners must have their `README.md` written in English. Do not be afraid
-of your English skills, as the open source community will fix your errors.
-
-Of course, you are welcome to write documentation in other languages;
-just name them appropriately (e.g. `README.ja.md`).
-
-### 4.2. Maintain a changelog
-
-PostCSS runners must describe changes of all releases in a separate file,
-such as `ChangeLog.md`, `History.md`, or with [GitHub Releases].
-Visit [Keep A Changelog] for more information on how to write one of these.
-
-Of course you should use [SemVer].
-
-[Keep A Changelog]: http://keepachangelog.com/
-[GitHub Releases]: https://help.github.com/articles/creating-releases/
-[SemVer]: http://semver.org/
-
-### 4.3. `postcss-runner` keyword in `package.json`
-
-PostCSS runners written for npm must have the `postcss-runner` keyword
-in their `package.json`. This special keyword will be useful for feedback about
-the PostCSS ecosystem.
-
-For packages not published to npm, this is not mandatory, but recommended
-if the package format is allowed to contain keywords.
projects / dotfiles / .git / blobdiff