Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Add block submission guidelines. #23545

Merged
merged 23 commits into from
Aug 10, 2020
Merged

Documentation: Add block submission guidelines. #23545

Changes from 2 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
8e0b3f0
Rough document outline.
StevenDufresne Jun 29, 2020
dba7465
A few updates.
StevenDufresne Jun 29, 2020
4d267fa
Update categories.
StevenDufresne Jun 30, 2020
815f43d
Lowercase the categories.
StevenDufresne Jun 30, 2020
e2b5a06
Fix embed category.
StevenDufresne Jul 1, 2020
0a3ed50
Prefer 'block editor' to 'gutenberg'.
StevenDufresne Jul 1, 2020
6661c0a
Includes example data.
StevenDufresne Jul 1, 2020
bb9631d
Change sentence and capital case 'block editor'.
StevenDufresne Jul 1, 2020
f70084f
update the intro sentence.
StevenDufresne Jul 1, 2020
717d26c
Fix formatting.
StevenDufresne Jul 2, 2020
c14048c
Fix the submit sections.
StevenDufresne Jul 2, 2020
488745c
Remove empty lines.
StevenDufresne Jul 6, 2020
34203f1
Use more contextual link text
ryelle Jul 9, 2020
cb7e2e6
Update block.json description
ryelle Jul 9, 2020
dd80b7e
update anchor link for keywords
jeffpaul Jul 10, 2020
b1f8072
Replace paragraphs based on feedback.
StevenDufresne Jul 21, 2020
5bbfa00
Update block directory references to be capital case.
StevenDufresne Jul 21, 2020
4e8e184
Update example copy.
StevenDufresne Jul 21, 2020
844db57
Fix merge conflict.
StevenDufresne Jul 21, 2020
2657763
Update copy that points to example block.json.
StevenDufresne Jul 21, 2020
c429c19
Update again.
StevenDufresne Jul 21, 2020
f056819
Update last property.
StevenDufresne Jul 21, 2020
b0e47b7
Change example callout.
StevenDufresne Jul 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 86 additions & 0 deletions ...s-developers/developers/tutorials/create-block/submitting-to-block-directory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
#Share your Gutenberg Block with the World
StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved
So you’ve created an awesome block have you? Care to share? Here is some basic information on how to submit a block to the Block Directory.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would just say simply: "So you've created an awesome block? Care to share?"


**Contents**:
1. Help users understand your block
2. Analyze your plugin
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about renaming this section to "Provide data to the block directory"? Something about "Analyze your plugin" makes it sound automated, rather than curating data and describing your block(s)

Copy link
Contributor

@paaljoachim paaljoachim Jul 11, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here are some of my suggestions.

Share your Block

Contents:

  1. Help users understand your block
  2. Analyze your plugin? --> What does that mean? Using basic words to explain what it is.
    Does this mean explain what your plugin does? Explain how you made your plugin?

I would skip the use of the word awesome as it has really no meaning/purpose in a tutorial.
The user needs to figure out for themselves if their plugin is awesome and then have a need/want to share it with others.

@ryelle Kelly
Curating data I really do not understand what that means.

3. Zip & Submit


StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved
## Step 1: Help users understand your block
Providing straightforward, easy to understand block information is important to the block directory and our end users.

StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved
**Guidelines**:

- Name your block based on what it does
- Clearly describe your block
- Add Keywords for all contexts
- Choose the right category

### Name your block based on what it does
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should take a clearer position on block names (specifically names not titles). Especially the namespace part. Unsurprisingly there's not much consistency in the plugin directory.

At a quick glance, I see people using namespaces that are:

  • The plugin slug (like card-block/main, pdf-viewer-block/standard)
  • The block name (blockasaurus/blockasaurus)
  • The developer's employer (a8c/waves)
  • The author's nickname or initials (cgb/block-importdoc-block)

None of these are wrong because we haven't given anyone clear guidance as to what they should use. I don't have a strong opinion, but I do thing the first two dot points above are sub-optimal. Using a very generic suffix like blah/main or blah/standard seems unhelpful. So does repetition like blah/blah.

Maybe we should recommend developers pick a namespace to use across all of their blocks, like in the last two dot points?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am tempted to suggest the last 2 are suboptimal because company names and initials are more likely to be repeated where as the block's folder name must be unique. Are there any issues if we suggest the namespace must match the plugin directory folder?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I definitely think we should avoid cgb or other starter-content prefixes, since those are much more likely to collide.

The plugin slug will be unique in order to be uploaded to the directory, so that makes sense as a namespace to me. But I also think company name or username are fine too, and it can be left to the company/person to make sure they're not uploading multiple blocks with the same name. Initials are probably more likely to collide between people though, so I'd say discourage that.

Copy link
Contributor Author

@StevenDufresne StevenDufresne Jul 6, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another thing we should consider is that there is a desire to surface the block's name:
#16521

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Surfacing the block's name, to me, suggests that the unique plugin slug is the best route.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So is this decided, we'll require the plugin slug to be used as a prefix? Should that be added into the guidelines, or is it enough to add a check to the Block Checker?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Name your block based on what it does"

It would be good with some example use cases to give a more detailed approach to how someone should approach the naming of their block. Have more detailed guidelines to a naming scheme as you are talking about above here.

The guidelines also need to show examples of naming, describing, keywords and choosing the right category.
That can mean use a Create a Block documentation they should follow in getting these things right. (At present I do not know if the Create a Block documentation gives this needed information.)

Bottom line is that we can not assume a person will understand but we need to give clear guidelines to how things should be done.

Users typically search the block directory within gutenberg and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it's needed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove gutenberg in favor of block editor or editor window
"Users typically search the block directory directly from the editor, doing so when actively editing a post. For example, a user may search...


**Not So Good**: WebTeam5 Image Works
**Good**: Responsive Image Slider by WebTeam5

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is very helpful to have additional examples.

**Question: What happens when there are multiple blocks with similar names?**
Try your best to make your block's name functional and unique to make it stand out. Look for applicable synonyms or include a prefix if necessary.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here it would be good to just mention that it is good to include a prefix. (Regarding the conversation above this might be changed to remember to include a prefix.)


StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved
### Clearly describe your block
The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block's description within Gutenberg where space can be limited. Try to keep it short and concise.

**Not So Good**: The best way to show images on your website using jQuery and CSS.
**Good**: An easy to use, responsive, Image gallery block.

StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved
**Tip**: It’s not about marketing your block, in fact we want to avoid marketing in blocks. You can read more about it in the [plugin guidelines]. Stick to being as clear as you can. The block directory will provide metrics to let users know how awesome your block is!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The above is not clear for me.
I would skip the first sentence, and instead add something like the below.

You can read more about marketing your block in the plugin guidelines. The Block Directory will provide metrics to let users know helpful your block is.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think without that first sentence it would be hard to understand the context. I think It may be better to remove it instead.

### Add Keywords for broader context
Keywords add extra context to your block and make it more likely to be found in the inserter.

Examples for an Image Slider block:
- slider
- carousel
- gallery

[Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keyword) about keywords.

StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved
### Choose the right category
Gutenberg allows you to indicate which category your block fits in. Choosing the right category makes it easy for users to find in the Gutenberg menu.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Block Editor allows you to indicate the category your block belongs in, making it easier for users to locate your block in the menu.


**Possible Values**:
- Common
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This list is outdated, see: #19279

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This list was taken from the block-registration documentation. I'll update it there as well.

- Formatting
- Layout
- Widgets
- embed

[Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#category) about categories.

Wondering where to input all this information? Read the next section :)


StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved
## Step 2: Analyze your plugin

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Each block in your plugin needs to have a corresponding block.json file. This file provides important information about your block to the Block Directory.

What important information? Go straight to the point and give the details without it saying the word important. The files stores such and such information. Give a detailed overview of what the json file stores.

Kinda like.
The block.json file stores the location of your block's files as well as contextual information like the: name, description, keywords and category. In addition is also stores.....?

The `block.json` file lives in the root folder of your block and provides the Block Directory and Gutenberg important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Block plugins submitted to the Block Directory can contain multiple (typo) blocks only if they are children of a single parent/ancestor.

Rephrasing.
Block plugins submitted to the Block Directory should have one main block, but it can contain multiple child blocks.
For example, a list block can contain list-item child blocks. Child blocks must set the parent property in their block.json file.

Double check that the following is true for your block:
`editorScript` is pointing to the JavaScript bundle that includes all the code used in the **editor**.
`editorStyle` is pointing to the CSS bundle that includes all the css used in the **editor**.
`script` is pointing to the JavaScript bundle that includes all the code used on the **website**.
`style` is pointing to the CSS bundle that includes all the code used on the **website**.
I have included example data (Optional, but useful)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Include example data (optional, but useful).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed it to Includes example data (optional, but useful). because it makes more sense in the context of the Double check that the following is true for your block. It feels more natural to me. I could be wrong though? :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had to read this multiple times before I realized this meant the example property in block.json. I thought it was a note to yourself to come back and add example data 😅

Is the example data a requirement (or do we think it will be a requirement in the future)? We should either explain this better or drop it, IMO


Although it isn’t necessary that you have both an `editorScript/editorStyle` and `script/style` listed in your `block.json` we encourage the separation of code used for editing and code used for displaying your block in order to keep both interfaces running quickly.
StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved

The `block.json` file also contains other important properties. Take a look at an [example block.json](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#registering-a-block-type) file for reference.

StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved

## Step 3: Zip & Submit
The community is ecstatic you made it this far! Time to submit your plugin!
StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved

StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved
Take a few moments to read the block guidelines (https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md)

TODO - ADD MORE STUFF HERE


StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved