[Docs] Advanced Section

[janiceilene]

We haven't written an advanced section as part of our documentation updates.

Some of the topics we want to cover are:

• Incremental builds
• Writing gulpfiles using another language
• Creating custom registries
• Writing a plugin
• Extglobs
• Command line interface
• Writing an adapter

This list may be added to as we come across more.

Feel free to suggest additional topics!

[donpedro]

I'd love to see "Writing an adapter", an analog of the invaluable Writing a plugin docs. I might even be able to help with a first draft if I can get help with #2347 to figure out the questions I have on how to do it.

[janiceilene]

Thanks for the suggestion @donpedro! I've added it to the OP. If you have get all your questions answered and want to work on a first draft of the docs, let us know!

[donpedro]

Alright, I've got everything I needed to know figured out over on #2347. How can I help with docs?

I've got a bit of experience now with Writing an Adapter, but I know we're talking here about "Advanced Docs"; I'm not sure how advanced my knowledge is, I was thinking something more on the level of the existing docs for Writing a plugin. So if you have need for beginner-level docs maybe I can help.

Other things I could contribute if needed:

• Writing gulpfiles using another language: I'm writing everything in TypeScript (gulpfiles, plugins and adapters), so could talk about TypeScript specifically
• Tooling: We've got a pretty well-tuned setup to do live debugging in TypeScript (without transpiling) on gulp in vscode; I'm happy to do a writeup on that if you have a place for it

[phated]

@donpedro Sorry for not following up here quickly, I've been traveling extensively and haven't had much time to dive in deeply. I definitely think we can use some help on the documents you are suggesting. How would you like to contribute? We could set up a GoogleDoc or just interact on a PR—either works for us!

[donpedro]

Great! Your call; either of those is fine by me!

[pixeldesu]

I'd like to touch up on "Writing a plugin" as well, but I have some questions before I want to attempt that.

I would use the files from the tree https://github.com/gulpjs/gulp/tree/master/docs/writing-a-plugin and base the new documentation on that, I especially like the common example of gulp-prefixer. Something I want to do different tho is trying to keep everything in a single document if possible.

It requires a lot of cutting content etc. but I'd like to touch up on that:

• README.md: In itself a solid base, but the "What it does" section is just duplicated content if we already have split files to handle both buffers and streams. I'd leave the information around the flow of data, but generally drop the code examples as well as listing off parts of the API, as those always have the potential to become outdated, which requires additional maintenance.
• dealing-with-streams.md: This by itself is fine.
• using-buffers.md: This also is fine.
• recommended-modules.md: I feel like this can be dropped, or if really required merged into a "Useful resources" link list at the bottom.
• testing.md: This explanation also seems fine as it is.

For the different stream/buffer examples I'd probably condense the code to explaining the general method-based plugin structure and then only show the different stream handling code examples, but I guess that's best seen once written down.

guidelines.md

I want to propose adjusting the guidelines, since I don't really feel they guide a lot towards plugin writing.

Feedback to every guideline

1. Your plugin should not do something that can be done easily with an existing node module

👍

2. Your plugin should only do one thing, and do it well.

👍

3. Your plugin shouldn't do things that other plugins are responsible for

👎 This pretty much just collides with the statement above, it seems superfluous.

4. Your plugin must be tested

👎 It should be tested. The guidelines are entirely optional and the wording should follow that, it already just being mentioned is enough of a guidance.

5. Add gulpplugin as a keyword in your package.json so you show up on our search

9. Name your plugin appropriately: it should begin with "gulp-" if it is a gulp plugin

👍 But these should be condensed into a single guideline point, like "To increase the visibility of your plugin in the NPM ecosystem, consider prefixing it with gulp- and adding the gulpplugin keyword to your package.json."

6. Your plugin API should be a function that returns a stream

👎 It needs to anyway, doesn't it? Unless you do some weird wrapper-of-a-wrap constructing shenanigans.

7. Do not throw errors inside a stream

👎 I feel this is outside of just purely gulp-scope and is a general Streams practise that you should utilise the error event here. If at all, this should be mentioned in the "Handling streams" section, not here.

8. Prefix any errors with the name of your plugin

👍

10. The type of file.contents should always be the same going out as it was when it came in

👎 Once again something I feel that is a bit out of scope for gulp. Technically, if you know what you're doing you could get this to work, but I believe changing a stream to a buffer and vice versa in streams is generally disregarded.

11. Do not pass the file object downstream until you are done with it

👎 Makes absolutely sense, but it seems like a clear thing to do, which makes it somewhat superfluous.

12. Use file.clone() when cloning a file or creating a new one based on a file.

👎 I feel that's more of coding advice rather than a guideline and not really in scope here either.

13. Use modules from our recommended modules page to make your life easier

👎 I want to drop that file anyway. Aside that, a list of fixed things might change, especially the tools mentioned, into a non-preferred state. Also, this isn't really much of a guideline anyway, it's a recommendation.

14. Do NOT require gulp as a dependency or peerDependency in your plugin

👎 Once again a thing that's outside of gulp scope as this applies to any tooling-specific NPM module.

I don't think the guidelines are bad per se, but they are too long for what's it worth, a lot of it is too general for just gulp, and having everything explained with sometimes obvious examples also stretches it quite a bit.

Instead of using several bullet points per guideline I think a bit more elaborate sentences would help this a lot. This also would make the guidelines easier to read.

---

If you don't think this issue is the right place to discuss this, we could either move it into a discussion or leave it in the PR reviews once I've written things up!

[yocontra]

@pixeldesu Regarding the guidelines (I wrote them originally, and feel very strongly this was a good thing for us) they were intended for plugins that wanted to be shown on gulpjs.com - it's essentially acting as a quality barrier and a carrot at the end of the stick for people to do things the right way. This was all originally based on watching other plugin ecosystems go to shit, and trying to make sure ours didn't nosedive in a similar fashion. I still think being as explicit as possible in these guidelines of what not to do, and what to do to be featured on our website + generally be a good actor in the ecosystem is useful guidance - but obviously we can't force people to do anything, since anyone can publish gulp-* on NPM. If we want to rewrite them to be clearer and more concise I'm all for it - but I still think they should be strongly opinionated, even if it is outside of our responsibilities to tell people how to write their code (write tests, use streams properly, etc.).

[pixeldesu]

@contra it makes sense and I understand and agree with the goal of trying to hold a certain quality standard!

I just feel like a lot of the implementation-related information makes more sense in the fitting code/example section (if you're interested in writing a plugin you'll get to read those anyway). Not completely dropping them but rearranging and simplifying them is probably a way to go.

So, if we have a section in which we detail how to use streams, we can move the stream-related guidelines there and word them as a general best practise. This would fit at the moment as there is no strict enforcement of the key-points or manual checks by the maintainers.

Once some kind of workflow (like automated acceptance testing) has been established, the requirements could be reworded into a must to be displayed on the plugin listing.

Another example would be testing, which we also explain in the documentation, putting it into the developers hands and with that the best faith for them to also follow the example and implement it.

In those regards it's probably best if I just started writing things down and leave it up to PR reviews where we can adjust everything as needed based on feedback. I understand the goals and try to work them in to my best ability!

[phated]

@pixeldesu Yeah, I think that it is probably best to give feedback with PR review. There are some things that we might need to drop until further work is done, and we might want to include changes coming in 5.0