Home

Site Name: [site_name]
Repo Name: [repo_name]
WPE Install Name: [wpe_name]
Theme Name: [theme_name]

--

Development Notes

[site_name] uses git for version control (see repo). Version control allows us to track codebase history, maintain parallel tracks of development, and collaborate without stomping out each other's changes.

We use the feature branches for active development, and the master branch for releases.

Table of Contents

• Structure
  • Core Functionality Plugin
  • Theme
  • Code Compiling
  • File Organization
• Setup local development environment
• Small Change Workflow
• Feature Contribution Workflow
• Pushing changes to WPEngine
• Pushing changes using DeployHQ

Structure

Core Functionality plugin

Any functionality that is theme-independent belongs in the Core Functionality plugin. This includes registering custom post types, metaboxes, widgets... Anything a user would reasonably expect to still exist after changing themes. More information.

We're using Carbon Fields for metaboxes. The ea_cf() helper function is used to access this data. See custom-fields.php for metabox registration, and custom-fields-helper.php for more information on the helper function.

Theme

Any theme dependencies on functionality plugins should be built with the use of do_action(), apply_filters(), or function_exists().

In short, changing to the default theme should not trigger errors on a site. Nor should disabling a functionality plugin - every piece of code should be decoupled and use standard WordPress paradigms (hooks) for interacting with one another.

Code Compiling

We are using CodeKit to compile and compress SCSS into minified CSS, and JS into a combined and minified JS file. You can use an alternative tool (ex: Prepos or gulp) but make sure to configure it to match the file organization below.

File Organization

Project structure unity across projects improves engineering efficiency and maintainability. We believe the following structure is segmented enough to keep projects organized—and thus maintainable—but also flexible and open ended enough to enable engineers to comfortably modify as necessary. All projects should derive from this structure:

|- assets/
|  |- images/ ____________________________ # Theme images
|  |- fonts/ _____________________________ # Custom/hosted fonts
|  |- icons/ _____________________________ # SVG Icons
|  |- js/
|    |- src/ _____________________________ # Source JavaScript
|    |- global-min.js ____________________ # Concatenated and Minified JavaScript
|  |- css/
|    |- main.css _________________________ # Concatenated and Minified CSS
|    |- editor-style.css
|  |- scss/ ______________________________ # See below for details
|- inc/ __________________________________ # PHP classes and files
|- partials/ _____________________________ # Template parts
|- templates/ ____________________________ # Page templates

The scss folder is described separately, below to improve readability. It is based on How to structure a Sass project:

|- assets/scss/
|-- modules/              # Common modules
|   |-- _helpers.scss     # Helper mixins
|   ...
|
|-- partials/             # Partials
|   |-- _base.scss        # global project variables + import modules and vendors
|   |-- _reset.scss       # Reset
|   |-- _style-guide.scss # Main style guide for the site
|   ...
|
|-- vendor/                 # CSS or Sass from other projects
|   |-- _include-media.scss
|   ...
|
|-- main.scss            # primary Sass file for frontend
|-- editor-style.scss    # styles that apply only to backend editor

Setup local development environment

This workflow assumes your site is hosted at WPEngine. If hosted elsewhere, use the same basic approach but download a copy of your website using whatever tools your host provides.

1. Install WordPress locally. You can use MAMP, Local, or other tools. I also recommend you setup wp cli.
2. In the WPEngine Site Settings, go to Git Push and add your SSH public key as a developer. This will allow you to push code changes to WPEngine (more information)
3. In the WPEngine Site Settings, go to Backup Points, select the most recent backup, and click "Download Zip". You could download a full backup (and skip the steps below for sourcing media from production), but I like doing a partial backup excluding media. Select "Partial Backup" and check everything but "Media Uploads". Set the email address to your own and you'll be emailed a zip file.
4. Copy over the appropriate files to your local WP install (themes, plugins). Do not include the mu-plugins directory; that contains WPEngine specific code.
5. Import the database locally, using phpMyAdmin, direct SQL query, or Migrate DB Pro (pulling from production or staging).
6. Update the URLs in the local database. Using wp cli: wp search-replace $(wp option get siteurl) http://wp.dev/[~wpe_name~], where the last URL is your local site's URL. If you don't have wp cli, try Search Replace DB.
7. Delete the theme wp-content/themes/[~theme_name~] and the plugin wp-content/plugins/core-functionality.
8. At the top level of the site, in terminal run

• git init
• git remote add origin git@github.com:billerickson/[~repo_name~].git
• git pull origin master This will pull down the version controlled theme and plugin.

9. Add the staging and production remotes, for pushing updates:

• git remote add staging git@git.wpengine.com:staging/[~wpe_name~].git
• git remote add production git@git.wpengine.com:production/[~wpe_name~].git

If sourcing media from production

1. Install BE Media from Production in the wp-content/mu-plugins directory.
2. Create a local-settings.php file in wp-content/mu-plugins. Update the URL to match the source of media (ex: live site URL).

Small Change Workflow

This approach can be used for small changes that need to go live immediately.

1. Make sure you have an up-to-date copy of the repo locally (git pull origin master)
2. Make your small change directly to the master branch
3. Push to GitHub (git push origin master)
4. Push to staging environment so others can review (git push staging master)
5. Once approved, push to production environment (git push production master)

Feature Contribution Workflow

For larger features that will take time to implement, require extensive review, and/or have multiple people working on it, it's highly recommended you make your code changes in a separate branch. Once approved, this branch can be merged into master.

1. Create an issue for your bug/feature if one doesn't already exist
2. Make sure you have an up-to-date copy of the master branch locally. git pull origin master
3. Create a branch from master with the name matching the issue number. For instance, for issue #30 we would run git branch issue/30. Then checkout the branch: git checkout issue/30
4. Make your code changes to this branch
5. Submit a pull request describing the change and citing the original issue number.
6. If any changes are needed to your patch, make them to your branch and push up (git push origin issue/30). They will automatically appear in the pull request
7. Once the pull request is approved, the code will be merged into master. You may safely delete your branch.

Pushing changes to WPEngine

We use WPEngine's git push feature for pushing changes. First, provide your public key to a site administrator, so they can give you git push access. Then add the following remotes:

git remote add production git@git.wpengine.com:production/[~wpe_name~].git
git remote add staging git@git.wpengine.com:staging/[~wpe_name~].git

Once you've completed the Contribution Workflow above, you can push to production using: git push production master. For feature branches that require review, it's recommended that you Copy Live to Staging, then push changes to staging: git push staging issue/30. Once approved, these changes can be merged to master and pushed to production.

Pushing changes using DeployHQ

If WPEngine is no longer the host, or you are not comfortable with the command line, you can use DeployHQ instead. Set up a free account and configure two separate deployments: staging and production (or only one if using a host with no staging server). I recommend setting them to manual, not automatic, as the free account is limited to 10 deployments per day.

1. Make changes to the site (either locally or using GitHub visual editor).
2. If editing locally, push those changes to GitHub: git push origin master
3. Log into DeployHQ and deploy those changes to staging.
4. View the staging site and make sure everything works.
5. Log into DeployHQ and deploy those changes to production.