xwp / engineering-best-practices Goto Github PK

XWP Engineering Best Practices

Home Page: https://xwp-co.atlassian.net/wiki/spaces/KB

engineering-best-practices's Introduction

Introduction

Welcome to the XWP Engineering Best Practices. Many engineers before you have started on this same page and gone on to do the best work of their careers.

Audience

The XWP Engineering Best Practices are not intended to teach anyone to become an engineer. Rather, it is our aim to illustrate how to engineer the WordPress enterprise way. Therefore, these best practices are intended for capable engineers that need to get up to speed quickly on how we do engineering at XWP.

Goal

As a company, we strive to provide websites and components that yield a top-notch user experience. In order to improve efficiency, we need to standardize what we use and how we use it. Standardizing our tools, frameworks, libraries, style, version control, and even languages will allow us to better understand the inner workings of someone else's project and produce better solutions ourselves.

As such, our engineers should follow these best practices in all their work. Our best practices are not meant to be restrictive or comprehensive; we value your creativity. The aim is for these documents to provide a strong guidance, not an authoritative direction. It's our hope that these best practices will not only influence our engineers but community members as well.

Philosophy

At the very heart of XWP is content publishing, or user experience. WordPress, we firmly believe, is the best starting point to achieve this. We design and build custom publishing experiences for major companies and brands around the world. Our publishing experiences or websites are tailor-made for our clients and their specific needs.

As such, the content management experience cannot be made to be generic. We don't cut corners when it comes to user experience and interface. We don't take shortcuts that compromise the end experience for the user. We don't distribute pre-packaged, auto-generated user interfaces or components.

While our solutions are complex, we want our code, tools, processes, systems, and practices to be as simple as possible. Simplicity facilitates collaboration as there is a lower barrier of entry. This goes for things like PHP design patterns as well as workflows. We discourage practices such as writing extra levels of code abstraction (wrapping existing API's) as they complicate debugging and add another component that needs to be maintained.

We are constantly challenging ourselves and learning. Knowledge gives everyone a competitive edge. We must all continue to grow and if we stop growing individually or collectively and stop challenging ourselves to improve, we fall behind. For that reason, these documents are not set in stone and will change. Evolving these best practices through contributions is incredibly important to us.

Contributing

Please contribute via pull requests on GitHub or if you're a member of the team you can also draft changes to the GitBook directly. This documentation was originally forked from 10up in 2015 and modified for XWP and then in 2019 was updated and converted to a GitBook. We want to thank those, both at 10up and previous XWP alum, that put the effort into creating these best practices — starting all the way back in 2011. Reinventing the wheel is not our goal, while diverging and maintaining our own set of best practices is. To those that came before us, we salute you 🖖.

engineering-best-practices's People

Contributors

Stargazers

Watchers

Forkers

decisionary mdwpgithub seramade ravichdev itowhid06 zzap vishalkakadiya liambirt isabella232 dexit rbest abditolesa aclrys

engineering-best-practices's Issues

Flesh out PHP unit testing strategy

https://xwp.github.io/engineering-best-practices/php/#unit-testing

Include references to dev-lib

Add page for project workflows

Explain use of pull requests, our preview server setup, unit testing, Travis integration, code review, etc

Add description of using dependency injection

Needs to be added to PHP design patterns: https://xwp.github.io/engineering-best-practices/php/#design-patterns

Add Documentation for Connecting to Chassis (Vagrant) Databases

Connecting to an mysql database running in Chassis (or other Vagrant machine), requires some additional steps and connection process. This issue tracks that documentation.

Describe ways to pass data from PHP to Javascript

From @edmundcwm:

wp_localize_script() type-casts all values to string (as seen here) so on the JS side we’d need to parse them back to the intended type.

// foo.php
wp_localize_script( 'foo-js', 'fooObj', array( 'age' => 31 ) );

// foo.js
const age = fooObj.age;
console.log(typeof age); // "string" instead of "number"

But the newer wp_add_inline_script() works differently.

// bar.php
wp_add_inline_script( 'bar-js', 'const barObj = {age: 31}' );

// bar.js
const age = barObj.age;
console.log(typeof age); // "number"

Guess this is another good reason to use wp_add_inline_script().

Include reference for how to get a new site added to VIP preview server

Document use of foo-bar plugin scaffold

https://github.com/xwp/wp-foo-bar

And also the init script: https://gist.github.com/westonruter/70d226aae2c322e66467

Add PHP class autoloading to design patterns

https://xwp.github.io/engineering-best-practices/php/#design-patterns

Flesh out PHPCS standard with bells and whistles

There are goodies not in the WordPress standard for PHPCS which we would be good to adopt as standard.

Composer tips and suggestions

How to update just one dependency?
Explain how version constrains for packages in composer.json impact the results of composer update.
Suggest pinning packages to exact versions to avoid accidental updates. Explain how to do major version updates when dependencies are pinned.
Don't run composer update when you don't want to update all dependencies.
...

Add description about commit messages

Commit messages deliver a lot of information to a developer. There should be a paragraph dedicated to commit messages in workflows section.

Domain `docs.xwp.co` offline

When trying to visit docs.xwp.co I received an error that the domain was inaccessible. It has been this way for a few days now.

Just wanted to flag this as the site is a good resource that I like to share with folks. 😉

Create separate guide about Gutenberg development

Extending and modifying the WordPress block editor is becoming one of the common tasks nowadays.

We should consider creating a guide on how to best work with the Gutenberg codebase, taking advantage of the multitude of @wordpress JS packages, and dealing with the @wordpress/data layer.

Initial TOC links have a slash (/) in the url, causing 404's

The first 3 links in the Table of Contents on the Home page are leading to 404 pages. This is because the links have a (/) prior to the # tag.

The file update-toc.php needs to be updated to add a conditional (or something like that) that will remove the (/) in cases where the link simply points to an anchor on the page.

Add Travis CI to automatically call bin/update-toc.php

Changes can then be pushed up to GitHub.

Would this result in Travis running again?

Include Travis and pre-commit hook recommendations

Cover functional components and hooks in React guide

The current React guide should be updated to cover the latest best practices, i.e. using simple functional components along with both built-in and custom hooks.

Hooks and functional components are becoming an important part of React apps development, slowly but surely superseding the "traditional" class components and higher-order components.

Our docs should reflect this shift, promoting the most up-to-date approach to React development.

Grammar in Project Structure > Modular Code > Themes

In order to modify this run-on sentence, my suggestion is that we change:

Take a look at our Config-Driven WP project for some (dated) examples for a common approach we take for normalizing the theme's configuration into a config.php array which then be cleanly merged with a child theme's configuration array.

to:

Take a look at our Config-Driven WP project for some (dated) examples of a common approach we take at normalizing the theme's configuration into a config.php array. The config array can then be cleanly merged with a child theme's configuration array.