feat(gatsby-cli): Add a plugin authoring help in gatsby-cli

[frinyvonnick]

Description

It implements a help message about plugin authoring as suggested by @shannonbux

Related Issues

Related #13376

[marcysutton]

This file is changing as part of #13261, so we'll probably want to wait until that lands and update this URL.

[DSchau]

@marcysutton we can also create a short-link, e.g. https://gatsby.dev/how-plugins-work and probably should for links in the CLI.

[marcysutton]

ooh yes! the content referenced on that page is moving though. I think the best place will be: /docs/creating-plugins/

And /docs/creating-a-source-plugin/ or /docs/pixabay-source-plugin-tutorial/ for the tutorial link.

[frinyvonnick]

@marcysutton do you have a PR id where the page /docs/creating-plugins/ is created ?

[marcysutton]

It was in #13261, which has now been merged! I'll chat with the team about creating short links.

[frinyvonnick]

Thank you for your reviews @marcysutton and @DSchau 👍

[shannonbux]

This is looking great! @frinyvonnick do you know if this PR would make the command gatsby plugin show up when someone runs gatsby --help?

[frinyvonnick]

Sure but it displays the whole message maybe we should have a shorter message for top-level help command @shannonbux @marcysutton ?

[frinyvonnick]

@sidharthachatterjee does #13089 affect this PR ?

[frinyvonnick]

Thank you for your review @shannonbux 👍

[moonmeister]

Hmm. This will conflict with the future implementation of #10294. I don't think general info like this should be a top level command. @shannonbux 's recommendations for cli in #13376 were more appropriate.

I also think this brings up a larger conversation concerning CLI design. I've brought it up with Jason before but it probably needs to be a larger conversation. In relation to #10294 Should the comamand be gatsby add plugin <XYZ> or gatsby plugin add <XYZ> This matters when you starting get into using this for themes and templates. In the case of this CLI it's creating a repo from a template...almost exactly what the existing gatsby new cli does. Does that mean we should modify the existing new command to work for gatsby site starters and plugin starters (e.g. gatsby new plugin source or gatsby new site)?

This seems like a very important design decision for the future maintainability and UX of the CLI. Any decisions we make now, no matter how small, need to be maintained in the future. If we design well now we might be able to avoid breaking the API in the future and requiring a version bump.

@frinyvonnick Thanks for working on this. This really isn't about your work in particular as much as it is me being concerned about the future of the CLI.

Hope this all makes sense. This is a larger conversation that should probably be held outside of this particular PR, though it might hold up its merge. This discussion can continue here: #13537

[frinyvonnick]

Hi @moonmeister, thank you for your review 👍 I totally understand, I'll be patient till the discussion is over so I could finish this PR 😉

[shannonbux]

Ok, after reading @moonmeister's PR, I think these can work together. What if you change this one @frinyvonnick to say:

plugin [action] [plugin-name]      run commands pertaining to gatsby plugins

And then, when people run gatsby plugin --help, we can show this (@moonmeister can perhaps make these changes or perhaps already has?):

$ gatsby plugin --help

plugin add [plugin-name]           Installs npm package, adds plugin to `gatsby-config.js`, warns if further config is needed.
plugin remove [plugin-name]    Removes npm package from `node_modules` and `package.json`, removes config from `gatsby-config.js`
plugin config [plugin-name]      Runs through configuration options again for dev to change answers if desired, defaults to current config
plugin search [search term(s)] Searches the [plugin database](https://www.gatsbyjs.org/plugins/) and returns relevant options

Resources:
Using a plugin: 
- [What is a Plugin?](https://www.gatsbyjs.org/docs/what-is-a-plugin/)
- [Using a Plugin in Your Site](https://www.gatsbyjs.org/docs/using-a-plugin-in-your-site/)
- [What You Don't Need Plugins For](https://www.gatsbyjs.org/docs/what-you-dont-need-plugins-for/)
- [Loading Plugins from Your Local Plugins Folder](https://www.gatsbyjs.org/docs/loading-plugins-from-your-local-plugins-folder/)
- [Plugin Library](https://www.gatsbyjs.org/plugins/)

Creating a plugin:
- [Naming a Plugin](https://www.gatsbyjs.org/docs/naming-a-plugin/)
- [Files Gatsby Looks for in a Plugin](https://www.gatsbyjs.org/docs/files-gatsby-looks-for-in-a-plugin/)
- [Creating a Local Plugin](https://www.gatsbyjs.org/docs/creating-a-local-plugin/)
- [Creating a Source Plugin](https://www.gatsbyjs.org/docs/creating-a-source-plugin/)
- [Creating a Transformer Plugin](https://www.gatsbyjs.org/docs/creating-a-transformer-plugin/)
- [Submit to Plugin Library](https://www.gatsbyjs.org/contributing/submit-to-plugin-library/)
- [Pixabay Source Plugin Tutorial](https://www.gatsbyjs.org/docs/pixabay-source-plugin-tutorial/)
- [Maintaining a Plugin](https://www.gatsbyjs.org/docs/maintaining-a-plugin/)
- Join Discord #plugin-authoring channel to ask questions!

Run `gatsby plugin --help` anytime you'd like to see this information again. Thank you!

Is this too insanely long?

[moonmeister]

I'm leaning towards insanely long. What if we did something like gatsby plugin info or gatsby plugin docs that way help is short and we can move these links there. In the future you could even include the name of a specific plugin after an it'd return the readme for that plugin.

[frinyvonnick]

So @shannonbux this PR is paused until gatsbyjs/rfcs#38 is merged ?

[moonmeister]

Sounds like we can probably move forward...the CLI implementation just needs to be decided.

[shannonbux]

Great suggestion @moonmeister. How about this?

plugin [action] [plugin-name]      run commands pertaining to gatsby plugins

And then, when people run gatsby plugin --help, we can show this:

$ gatsby plugin --help

plugin add [plugin-name]           Installs npm package, adds plugin to `gatsby-config.js`, warns if further config is needed.
plugin remove [plugin-name]    Removes npm package from `node_modules` and `package.json`, removes config from `gatsby-config.js`
plugin config [plugin-name]      Runs through configuration options again for dev to change answers if desired, defaults to current config
plugin search [search term(s)] Searches the [plugin database](https://www.gatsbyjs.org/plugins/) and returns relevant options
plugin docs                                 Directs you to docs about using and creating plugins

Run `gatsby plugin --help` anytime you'd like to see this information again. Thank you!

If you all are good with this idea, with these changes the PR could then be ready to merge imho

[frinyvonnick]

Seems nice to me @shannonbux 👍! @moonmeister what do you think of it ?

[moonmeister]

@shannonbux @frinyvonnick looks good.

[frinyvonnick]

I moved to gatsby plugin docs command but can't figure how to add the sentence Run gatsby plugin --help anytime you'd like to see this information again. Thank you! in the help message 😢

@shannonbux is this extra message mandatory ?

[moonmeister]

Looks good!

[frinyvonnick]

Someone of the @gatsbyjs/core could review it ? 😄

[DSchau]

Looks mostly great--thanks!

Few other comments (that I can't leave suggestions for):

gatsby plugin should have documentation, specifically in:

• docs/docs/gatsby-cli.md
• packages/gatsby-cli/README.md

Thanks for this--and your patience!

[frinyvonnick]

Thanks @DSchau for your review, I'll update documentation as soon as possible 👍

[DSchau]

Thanks for this!

[DSchau]

Successfully published:

• gatsby-cli@2.6.5
• gatsby@2.8.5

Thanks so much!