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

Jump to bottom

Adds a README.md file to the project scaffolded by create-block #53896

Open
wants to merge 2 commits into
base: trunk
Choose a base branch
from
Open

Adds a README.md file to the project scaffolded by create-block #53896

wants to merge 2 commits into from

Conversation

mburridge
Copy link
Contributor

What?

Adds a README.md template file to the create-block package. This file contains an overview of the project scaffolded by create-block and descriptions of the files and directories contained within the project. There are also links to external information sources.

Why?

Useful as a learning aid and as a reference when creating a new project with the create-block package.

Testing Instructions

To test locally run each of the following commands from within packages/create-block/lib:

node index.js test-create-block
node index.js --variant dynamic test-create-block-dyn

Check that the README.md files generated each contain different content for static and dynamic blocks and that they accurately reflect the respective projects.

Remember to delete the test-create-block and test-create-block-dyn directories when done!

Discussion point

This file will not be generated if the --no-plugin flag is defined. Should lines 59 to 84 instead be put in a separate README.md file in the block directory?

@mburridge mburridge added [Type] Developer Documentation Documentation for developers [Tool] Create Block /packages/create-block Developer Experience Ideas about improving block and theme developer experience labels Aug 23, 2023
ryanwelcher
ryanwelcher requested changes Aug 23, 2023
View reviewed changes
Copy link
Contributor

@ryanwelcher ryanwelcher left a comment

Choose a reason for hiding this comment

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

This is great work and will be a big help! I made a couple suggestions and my only overall note is to try to add external reference links to all the sections if possible to create a better learning path.

packages/create-block/lib/templates/plugin/README.md.mustache
## Files and directories

### build
The `build` directory is where the final deployable build of the block will go. The build process will put compiled versions of files from the `src` directory in here. You should never need to touch this directory directly.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
The `build` directory is where the final deployable build of the block will go. The build process will put compiled versions of files from the `src` directory in here. You should never need to touch this directory directly.
The build process will put compiled versions of files from the `src` directory in here. You should never need to touch this directory directly.

packages/create-block/lib/templates/plugin/README.md.mustache
The `build` directory is where the final deployable build of the block will go. The build process will put compiled versions of files from the `src` directory in here. You should never need to touch this directory directly.

### node_modules
The `node_modules` directory is where all the modules that the build process depends on live. Again you should never need to directly modify the contents of this directory. To install packages here use `npm install {package-name}` or define it as a 'dependency' or 'devDependency' in `package.json`.
Copy link
Contributor

Choose a reason for hiding this comment

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

Should we add a link here similar to package.json?

packages/create-block/lib/templates/plugin/README.md.mustache
`edit.js` exports a component, `Edit()`, that is rendered in the editor and so determines how the block appears and functions within the editor. It is where you will define the markup and content of the block. It is also where you will provide controls for the user to interact with the block and customize the appearance and content of the block. The `Edit()` component defined in this file receives a props object which among other things will contain the attributes defined in `block.json`. `setAttributes` is also passed to allow you to update the attribute values.

#### src/editor.scss
`editor.scss` is a file containing SCSS that styles the appearance of the block in the block editor. It requires a compile step which will result in `build/index.css`.
Copy link
Contributor

Choose a reason for hiding this comment

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

SCSS is an extension. We should be clear that this file is CSS that will be compiled using Sass

Suggested change
`editor.scss` is a file containing SCSS that styles the appearance of the block in the block editor. It requires a compile step which will result in `build/index.css`.
`editor.scss` is a file containing CSS that will be compiled using [Sass](https://sass-lang.com/) that styles the appearance of the block in the block editor. It requires a compile step which will result in `build/index.css`.

packages/create-block/lib/templates/plugin/README.md.mustache

{{#isDynamicVariant}}
#### src/render.php
This file performs the server-side rendering in a **dynamic** block.
Copy link
Contributor

Choose a reason for hiding this comment

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

Is there a link we can add here?

packages/create-block/lib/templates/plugin/README.md.mustache
A manifest file for node that contains metadata about the project. Dependencies for the project and scripts are defined in this file. See [this guide](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) to `package.json` to learn about the options defined here.

### README.md
[This file]
Copy link
Contributor

Choose a reason for hiding this comment

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

Probably don't need this section at all. It's a bit self-evident :) Just my opinion, not strongly held though.

packages/create-block/lib/templates/plugin/README.md.mustache

{{title}} is a {{#isStaticVariant}}static{{/isStaticVariant}}{{#isDynamicVariant}}dynamic{{/isDynamicVariant}} block scaffolded by {{author}} using the `@wordpress/create-block` package.

## The structure of the project
Copy link
Contributor

Choose a reason for hiding this comment

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

Love this.

packages/create-block/lib/templates/plugin/README.md.mustache
│
│── package.json
│
│── README.md (this file)
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
│── README.md (this file)
│── README.md

packages/create-block/lib/templates/plugin/README.md.mustache
{{/isStaticVariant}}

#### src/style.scss
`style.scss` contains SCSS that styles the appearance of the block in the front end. It will also be used in the editor unless a style defined here is over-ridden by one in `editor.scss`. This file requires a compile step which will result in `build/style-index.css`.
Copy link
Contributor

Choose a reason for hiding this comment

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

Same note about SCSS being an extension.

Suggested change
`style.scss` contains SCSS that styles the appearance of the block in the front end. It will also be used in the editor unless a style defined here is over-ridden by one in `editor.scss`. This file requires a compile step which will result in `build/style-index.css`.
`style.scss` contains CSS that will be compiled using [Sass](https://sass-lang.com/] and styles the appearance of the block in the front end. It will also be used in the editor unless a style defined here is over-ridden by one in `editor.scss`. This file requires a compile step which will result in `build/style-index.css`.

@ryanwelcher
Copy link
Contributor

ryanwelcher commented Aug 23, 2023 •
edited
Loading

Those failing tests are due to this PR adding a new file and it will need to be updated here I believe

@gziolo
Copy link
Member

gziolo commented Aug 24, 2023 •
edited
Loading

It's a great idea to add documentation around the scaffolded project structure. Thank you so much for opening the PR.

I only wanted to highlight two important aspect to consider:

@gziolo gziolo added the [Status] Stale Gives the original author opportunity to update before closing. Can be reopened as needed. label Dec 11, 2024
@gziolo
Copy link
Member

gziolo commented Dec 11, 2024 •
edited
Loading

@ryanwelcher, is there any follow-up work planned here?

I added the [Status] Stale label to the PR. I am happy to remove it as soon as we get clarification about the next steps.

@github-actions GitHub Actions
Copy link

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: mburridge <mburridge@git.wordpress.org>
Co-authored-by: ryanwelcher <welcher@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@ryanwelcher
Copy link
Contributor

I'm not sure if @mburridge is still contributing. I can pick this up and move off of his fork to move it forward.

@ryanwelcher ryanwelcher self-assigned this Dec 11, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ryanwelcher ryanwelcher ryanwelcher requested changes

@juanmaguitar juanmaguitar Awaiting requested review from juanmaguitar

@justintadlock justintadlock Awaiting requested review from justintadlock

@ndiego ndiego Awaiting requested review from ndiego

@gziolo gziolo Awaiting requested review from gziolo gziolo is a code owner

Requested changes must be addressed to merge this pull request.

Assignees

@ryanwelcher ryanwelcher

Labels
Developer Experience Ideas about improving block and theme developer experience [Status] Stale Gives the original author opportunity to update before closing. Can be reopened as needed. [Tool] Create Block /packages/create-block [Type] Developer Documentation Documentation for developers
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@mburridge @ryanwelcher @gziolo