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 all 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
101 changes: 101 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,101 @@
# Share your Block with the World

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

## Step 1: Help users understand your block

It is important to the Block Directory and our end users to provide easy to understand information on how your block was created.

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 the Block Editor 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.

**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.)

### 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 the Block Editor where space can be limited. Try to keep it short and concise.
StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved

**Not So Good**: The best way to show images on your website using jQuery and CSS.
**Good**: A 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 about keywords.](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keywords)

StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved
### Choose the right category

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.
StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved

**Possible Values**:
- text
- media
- design
- widgets
- embed

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

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

## Step 2: Analyze your plugin
Each block in your plugin should have a corresponding `block.json` file. This file provides the Block Directory 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.

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.....?

Block plugins submitted to the Block Directory can contain mutliple blocks only if they are children of a single parent/ancestor. There should only be one main block. For example, a list block can contain list-item blocks. Children blocks must set the `parent` property in their `block.json` file.

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**.

We encourage the separation of code by using both editorScript/editorStyle and script/style files listed in your block.json to keep the backend and frontend interfaces running smoothly. Even though only one file is required.

Here is an example of a basic block.json file.

StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved
```json
{
"name": "plugin-slug/image-slider",
"title": "Responsive Image Slider",
"description": "A responsive and easy to use image gallery block.",
"keywords": [ "slider", "carousel", "gallery" ],
"category": "media",
"editorScript": "file:./dist/editor.js",
}
```

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) for additional properties to be included in the block.json file.

StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved

## Step 3: Zip & Submit

The community is thankful for your contribution. It is time to submit your plugin.

Go through [the block guidelines](https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md). Create a zip file of your block and go to the [block plugin validator](https://wordpress.org/plugins/developers/block-plugin-validator/) and upload your plugin.

StevenDufresne marked this conversation as resolved.
Show resolved Hide resolved