Skip to content

Commit d634e95

Browse files
tamj0rd2phated
authored andcommitted
Docs: Fix sub-lists in writing-a-plugin guidelines (#1955)
1 parent a2badd6 commit d634e95

File tree

1 file changed

+26
-26
lines changed

1 file changed

+26
-26
lines changed

docs/writing-a-plugin/guidelines.md

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -5,45 +5,45 @@
55
[Writing a Plugin](README.md) > Guidelines
66

77
1. Your plugin should not do something that can be done easily with an existing node module
8-
- For example: deleting a folder does not need to be a gulp plugin. Use a module like [del](https://github.com/sindresorhus/del) within a task instead.
9-
- Wrapping every possible thing just for the sake of wrapping it will pollute the ecosystem with low quality plugins that don't make sense within the gulp paradigm.
10-
- gulp plugins are for file-based operations! If you find yourself shoehorning a complex process into streams just make a normal node module instead.
11-
- A good example of a gulp plugin would be something like gulp-coffee. The coffee-script module does not work with Vinyl out of the box, so we wrap it to add this functionality and abstract away pain points to make it work well within gulp.
8+
- For example: deleting a folder does not need to be a gulp plugin. Use a module like [del](https://github.com/sindresorhus/del) within a task instead.
9+
- Wrapping every possible thing just for the sake of wrapping it will pollute the ecosystem with low quality plugins that don't make sense within the gulp paradigm.
10+
- gulp plugins are for file-based operations! If you find yourself shoehorning a complex process into streams just make a normal node module instead.
11+
- A good example of a gulp plugin would be something like gulp-coffee. The coffee-script module does not work with Vinyl out of the box, so we wrap it to add this functionality and abstract away pain points to make it work well within gulp.
1212
1. Your plugin should only do **one thing**, and do it well.
13-
- Avoid config options that make your plugin do completely different tasks
14-
- For example: A JS minification plugin should not have an option that adds a header as well
13+
- Avoid config options that make your plugin do completely different tasks
14+
- For example: A JS minification plugin should not have an option that adds a header as well
1515
1. Your plugin shouldn't do things that other plugins are responsible for
16-
- It should not concat, [gulp-concat](https://github.com/contra/gulp-concat) does that
17-
- It should not add headers, [gulp-header](https://www.npmjs.com/package/gulp-header) does that
18-
- It should not add footers, [gulp-footer](https://www.npmjs.com/package/gulp-footer) does that
19-
- If it's a common but optional use case, document that your plugin is often used with another plugin
20-
- Make use of other plugins within your plugin! This reduces the amount of code you have to write and ensures a stable ecosystem.
16+
- It should not concat, [gulp-concat](https://github.com/contra/gulp-concat) does that
17+
- It should not add headers, [gulp-header](https://www.npmjs.com/package/gulp-header) does that
18+
- It should not add footers, [gulp-footer](https://www.npmjs.com/package/gulp-footer) does that
19+
- If it's a common but optional use case, document that your plugin is often used with another plugin
20+
- Make use of other plugins within your plugin! This reduces the amount of code you have to write and ensures a stable ecosystem.
2121
1. Your plugin **must be tested**
22-
- Testing a gulp plugin is easy, you don't even need gulp to test it
23-
- Look at other plugins for examples
22+
- Testing a gulp plugin is easy, you don't even need gulp to test it
23+
- Look at other plugins for examples
2424
1. Add `gulpplugin` as a keyword in your `package.json` so you show up on our search
2525
1. Your plugin API should be a function that returns a stream
26-
- If you need to store state somewhere, do it internally
27-
- If you need to pass state/options between plugins, tack it on the file object
26+
- If you need to store state somewhere, do it internally
27+
- If you need to pass state/options between plugins, tack it on the file object
2828
1. Do not throw errors inside a stream
29-
- Instead, you should emit it as an **error** event.
30-
- If you encounter an error **outside** the stream, such as invalid configuration while creating the stream, you may throw it.
29+
- Instead, you should emit it as an **error** event.
30+
- If you encounter an error **outside** the stream, such as invalid configuration while creating the stream, you may throw it.
3131
1. Prefix any errors with the name of your plugin
32-
- For example: `gulp-replace: Cannot do regexp replace on a stream`
33-
- Use gulp-util's [PluginError](https://github.com/gulpjs/gulp-util#new-pluginerrorpluginname-message-options) class to make this easy
32+
- For example: `gulp-replace: Cannot do regexp replace on a stream`
33+
- Use gulp-util's [PluginError](https://github.com/gulpjs/gulp-util#new-pluginerrorpluginname-message-options) class to make this easy
3434
1. Name your plugin appropriately: it should begin with "gulp-" if it is a gulp plugin
35-
- If it is not a gulp plugin, it should not begin with "gulp-"
35+
- If it is not a gulp plugin, it should not begin with "gulp-"
3636
1. The type of `file.contents` should always be the same going out as it was when it came in
37-
- If file.contents is null (non-read) just ignore the file and pass it along
38-
- If file.contents is a Stream and you don't support that just emit an error
39-
- Do not buffer a stream to shoehorn your plugin to work with streams. This will cause horrible things to happen.
37+
- If file.contents is null (non-read) just ignore the file and pass it along
38+
- If file.contents is a Stream and you don't support that just emit an error
39+
- Do not buffer a stream to shoehorn your plugin to work with streams. This will cause horrible things to happen.
4040
1. Do not pass the `file` object downstream until you are done with it
4141
1. Use [`file.clone()`](https://github.com/gulpjs/vinyl#clone) when cloning a file or creating a new one based on a file.
4242
1. Use modules from our [recommended modules page](recommended-modules.md) to make your life easier
4343
1. Do NOT require `gulp` as a dependency or peerDependency in your plugin
44-
- Using gulp to test or automate your plugin workflow is totally cool, just make sure you put it as a devDependency
45-
- Requiring gulp as a dependency of your plugin means that anyone who installs your plugin is also installing a new gulp and its entire dependency tree.
46-
- There is no reason you should be using gulp within your actual plugin code. If you find yourself doing this open an issue so we can help you out.
44+
- Using gulp to test or automate your plugin workflow is totally cool, just make sure you put it as a devDependency
45+
- Requiring gulp as a dependency of your plugin means that anyone who installs your plugin is also installing a new gulp and its entire dependency tree.
46+
- There is no reason you should be using gulp within your actual plugin code. If you find yourself doing this open an issue so we can help you out.
4747

4848
## Why are these guidelines so strict?
4949

0 commit comments

Comments
 (0)