Blocks: load each block from a separate file.

[jeherve]

Changes proposed in this Pull Request:

As we work to add several new modules, the existing module/blocks.php is updated quite often. It causes a few issues:

• The file keeps getting longer and longer.
• The longer the file, the longer it takes to skim through it.
• Everyone working on that file ends up having to rebase frequently because we are merging changes to that file often.
• Keeping the file in sync with WordPress.com can be more work if someone does not commit their matching WordPress.com diff immediately after merging a Jetpack PR.

Splitting things into different files makes things easier to maintain for everyone.

Internal reference: pafL3P-io-p2

Testing instructions:

• Go to Posts > Add New
• Do you see, and can you use all blocks?
• Yay.

Proposed changelog entry for your changes:

• None.

[matticbot]

Caution: This PR has changes that must be merged to WordPress.com
Hello jeherve! These changes need to be synced to WordPress.com - If you 're an a11n, please commandeer, review, and approve D23984-code before merging this PR. Thank you!

[jetpackbot]

Thank you for the great PR description!

When this PR is ready for review, please apply the [Status] Needs Review label. If you are an a11n, please have someone from your team review the code if possible. The Jetpack team will also review this PR and merge it to be included in the next Jetpack release.

Scheduled Jetpack release: March 5, 2019.
Scheduled code freeze: February 26, 2019

Generated by 🚫 dangerJS against 3f6b242

[matticbot]

jeherve, Your synced wpcom patch D23984-code has been updated.

[sirreal]

Should these generic blocks even live under modules, or could they move up a level?

Asking the dumb question in case you didn't consider it. I understand there may be reason to keep it where it is.

This file is unusual, and is not an actual module as such.

This always concerned me 🙂

[jeherve]

I did not consider it, so thanks for asking. I don't have a good answer here. Why not I suppose? I don't really have a preference here, so happy to change that if necessary. Just say the word :)

[ockham]

Should these generic blocks even live under modules, or could they move up a level?

It's even weirder on WP.com where I think the modules dir was only created to hold blocks.php. All other JP modules map to subdirs in mu-plugins and admin-plugins IIRC.

I'm all for moving things elsewhere, but I'm not sure what would be the best location on WP.com -- we should probably figure that out.

[ockham]

BTW thanks for this. Updating modules/blocks.php has been kind of annoying during development of #11212.

(I mean it will be quite annoying to do it again if this one lands before, but at least things will be easier in the long run 😅 )

[matticbot]

jeherve, Your synced wpcom patch D23984-code has been updated.

[jeherve]

@sirreal @ockham Thank you both for the feedback. I moved things around in 3f6b242.

• The blocks now live in /blocks at the root of the plugin.
• We don't really need modules/blocks.php anymore. I moved the loading of all the blocks inside the Gutenberg class, to keep everything in one place.

[jeherve]

It's even weirder on WP.com where I think the modules dir was only created to hold blocks.php. All other JP modules map to subdirs in mu-plugins and admin-plugins IIRC.

I'm all for moving things elsewhere, but I'm not sure what would be the best location on WP.com -- we should probably figure that out.

I placed them in wp-content/mu-plugins/jetpack/blocks in my diff so far because it makes syncing easier (I don't have to worry about setting 2 different paths in load_independent_blocks), but I am happy to reconsider.

[lezama]

Thanks for working on this @jeherve!

[jeherve]

Since we've talked about the blocks' location, here is how I would personally envision the blocks's file structure in the future:

1. _inc/client/blocks for the blocks’s JSX (once we move those files from Calypso to Jetpack)
2. _inc/blocks for the built blocks (it is already like that today, those are the files that get shipped to customers). This could also be changed to _inc/build/blocks to match the other things we build within Jetpack.
3. /blocks for the blocks’ PHP files (those live in a single modules/blocks.php today, and that is what this PR aims to change)

[simison]

Not saying we should always follow core's patterns but just for the record and awereness:

https://github.com/WordPress/gutenberg/tree/8ba4a209b4b1a1bf6e3037d3dea86392d03c2c44/packages/block-library/src

• a folder per block under block-library root folder
• PHP & JS related to each block under same folder
• Root folder has package.json (and blocks are under src) as Gutenberg is a monorepo and they publish these folders to NPM.

[jeherve]

@simison I like it! That actually makes a lot of sense, especially in the context of publishing every block to npm separately.

On our end, that structure would probably be easier to understand for new contributors once we bring the blocks's JSX to Jetpack.

I have 2 questions about this approach:

• Where would we put the built blocks' code in that scenario?
• Would it be confusing for blocks like Markdown or Contact Form, where the blocks' PHP lives within the module? Would one expect the block's PHP code in there, since that's how it works for independent blocks?

[simison]

Great questions!

Where would we put the built blocks' code in that scenario?

I would probably try to re-align with the rest of Jetpack and:

• Build files in_inc/build folder (so _inc/build/gutenberg-extensions?)
• Have both, production .min.js and development .js files shipped in Jetpack just like we do for the rest of the assets so that folks can debug without re-compiling everything and switch between the two using SCRIPT_DEBUG constant.

I recognize these are not something we can do now but it's good to envision a bit further into the future at this point.

Would it be confusing for blocks like Markdown or Contact Form, where the blocks' PHP lives within the module? Would one expect the block's PHP code in there, since that's how it works for independent blocks?

I think it's okay; that's basically how core blocks work, too. They rely on APIs and functionality from other files (think search block, recent posts block, or upcoming comments block). I'd expect there to be at least one PHP file for each block where we'd actually define at least dependencies for the block so that at least those would be in the same place with JS sources.

I would also take the chance and rename the root folder to something else than blocks since we technically have all sorts of Gutenberg integrations, not just blocks. But I recognise "blocks" has become common language for these already so I don't feel strongly about this.

How does that sound?

[simison]

_inc/build/gutenberg-extensions

On 2nd thought, we might also want to eventually phase out "gutenberg" term (and use "block editor" instead) so worth considering if we could avoid introducing it. Core has been doing similar changes recently.

So _inc/build/block-editor ?

[enejb]

Just some backround info as to why I placed blocks into /modules/blocks.php

It was mostly done for consistency.
We currently have module for shortcodes that lives inside there. /modules/shortcodes/* and /modules/shortcodes.php So it made sense to me for blocks to also live there that to be the same.

There is also some precedent on code that isn't exactly a module to live in that directory.

So my suggestion is to not have a special folded called blocks in jetpack. but to place the blocks code back in modules/blocks :)

[sirreal]

I haven't tested, but this seems to me like a nice change that will benefit developers. I like to know where things should go and understand why 🙂

Should all this live in one file? It's pretty clear to me that it should not. The whopping 7000+ line class.jetpack.php is a great example of when that pattern is left to run wild. I'm glad we're getting ahead of this one.

Should we call it blocks? 🤷‍♂️ I'm not sure. At this point it all seems to be all blocks. Seems descriptive at this time, that may change, naming things is hard. Good enough for now.

Should it live under modules? 🤷‍♂️ What's a module? Jetpack modules seem to be a specific thing with some expected behavior. The fact that it's strange enough that we need to mention in the header "Hey, this isn't actually a module" indicates to me that the location should raise some red flags.

Maybe blocks are modules? Why not? That's the paradigm for additional functionality that Jetpack has. Why not just make each block a module? It's probably just overhead, but these are the kind of lines we can draw that helps me to work effectively. If the contract with Jetpack is that it provides a core that modules can extend, maybe that's exactly what we should be doing.

This has gotten a bit philosophical so I'll bring it back home. I'm in favor of this change, but @Automattic/jetpack-crew should have the final say. At the end of the day, I don't care too much exactly where the files live, every decision has tradeoffs. I do think it's important we reason about why we make the decisions we do and consider alternatives.

[jeherve]

@dereksmart Could you weigh in on this maybe? Thank you!

[sirreal]

I haven't had time to test this, but I wanted to manifest my support of the general direction taken here.

I'll reference my more rambling thoughts with greater detail in another comment (#11286 (comment))

[jeherve]

Closing in favor of #11312, as the rebase was a nightmare :(