Process for Site Build Engineers

Important

If you are not directly involved with the WordPress.com Special Projects team, this page does not apply to you. Maybe you'll find it interesting though?

Introduction.

The introduction of this monorepo system is a fundamental shake-up for how we build partner projects. Typically we would silo everything to do with a project in private repos, minimising discoverability and making re-usability difficult, as a private silo does not encourage agnostic building.

Using this monorepo and its associated rules will cause initial small amounts of disruption, there's no getting around this. I would expect that within 3 months after launch, everyone should feel comfortable with the system.

At all points our main plan is to reduce disruption to your processes caused by this system. Please provide feedback to Engineering Leads early and often if you feel unnecessarily blocked.

Project Expectations.

Scoping.

During the scoping phase of your project (e.g after receiving i1 designs) please make a list of all custom blocks you feel will need to be developed as part of this project.

Next, go through that list and weed out any that can be achieved with custom block styles, or patterns.

Once you have a final(ish) list of required custom blocks, check this monorepo to see if any blocks here match or closely match your requirements. As this monorepo matures the likelihood of this will increase.

Lastly, you should now be left with a list of blocks that will need custom development for your project. Please ping engineering leads to have this list verified. Include in the ping:

• Project Name
• Figma Link
• Block list and anticipated areas these will be used

An engineering lead will approve your list and this will reduce project blocking once development starts.

Development.

Follow the appropriate pages in this wiki for creating a new block, or updating an existing block.

Delivery.

For project delivery the expectation is:

1. Custom developed blocks live in the monorepo, and your project handles its own custom styling of these.
2. The custom blocks used in the project will be installed as regular block plugins and not tracked in the project repo. This allows auto-updates to function as normal.

Exclusions.

There are cases where blocks can be excluded from the monorepo system and built siloed in the project private repo instead. Also some very specific internal server setups may also require this. This exclusion will typically be when a block is so complex and custom that it serves no predictable re-use for any other project. Please clear this with Engineering Leads and use this exception only when it's most applicable.