WordPress Development

WordPress is used at Middlebury by a variety of individuals and groups including faculty, staff, students, administrators, designers, developers, librarians, technologists, academic and administrative departments, offices, student organizations, courses, initiatives, projects and so on. This document compiles recommendations about how Wordpress at Middlebury should be configured, updated and maintained.

Initial Setup

The initial setup of WordPress requires:

cloning the Midd WordPress git repository
editing the config.php and .htaccess files
copying production database

Cloning the central repository

Your ssh keys must be authorized to access the central repository, or (if using GitHub) you need to add your ssh key to your account to access the repository. All anvil accounts' ssh keys have been authorized to do so on our internal git at the time of this writing. Contact Adam to add ssh keys for other machines (such as your desktop) if desired.

cd to your public_html directory on anvil:
```
cd ~/public_html/
```
clone the repository and create a working directory with git-clone:
```
git clone git@github.com:middlebury/wordpress.git wordpress
```
cd into new wordpress directory
```
cd wordpress
```
initialize submodules and then update:
```
git submodule init
```
```
git submodule update
```

Configuring WordPress

cd to your wordpress directory:
```
cd ~/public_html/wordpress/
```
Create a local copy of your WordPress configuration
```
cp wp-config.php-midd wp-config.php
```

Update local copy of WordPress configuration

-define('DB_NAME', 'username_wordpress');

+define('DB_NAME', 'yourname_wordpress');

-$base'/';

+$base'/~yourname/wordpress/';

Create a local copy of your .htaccess file:
```
cp .htaccess-midd .htaccess
```

Update local copy of .htaccess file:

-RewriteBase

+RewriteBase /~yourname/wordpress/

Copying production database to development

We maintain a set of development scripts that assist with copying sites from our production system to our development environment. Because our WordPress installation is so large and it takes so long to update all sites (~1 day), we normally only export a limited set of sites to development.

Put the development scripts in a non-web-accessible directory:
```
cd ~/
```
```
git clone git@github.com:middlebury/wordpress-tools.git
```
Follow the instructions in the README to add the scripts to your PATH and configure them.
Follow the instructions in the README to export a preconfigured list of sites or an individual site by id.

Working with domain mapping

There are several configuration changes that need to be made to enable domain mapping in development:

Edit your workstation's /etc/hosts file to add anvil's IP address for any domains you wish to test.
Edit anvil's apache configuration to point at your code directory for any domain you wish to test.
Edit wp-config.php and un-comment the line
```
define( 'SUNRISE', 'on' );
```

Make a symbolic link to sunrise.php:

ln -s wp-content/mu-plugins/wordpress-mu-domain-mapping/sunrise.php wp-content/sunrise.php

Edit your .htaccess file to make the RewriteBase /
Dump the WordPress database without re-writing the URLs.

Generally, testing domain mapping in development is not required.

Updating WordPress

Applying Core Updates

Save your .htaccess, and wp-config.php files outside of wordpress directory
```
mkdir ~/wp-settings/; cp .htaccess wp-config.php ~/wp-settings
```

Delete all files except the .git and .gitignore directories

find . -maxdepth 1 ! -name '.git*' ! -name '.' ! -name '..' -exec rm -Rf {} \;

Copy the WordPress codebase zip file to your WordPress directory and unzip
```
unzip latest.zip
```
cd into wordpress dir and move files to parent directory
```
cd wordpress
```
```
mv * ..
```
cd to main wordpress directory and delete empty wordpress directory and the zip file
```
cd ../
```
```
rm -r wordpress
```
```
rm latest.zip
```

Add and commit the changes (and additions/removals)

git add .

git add -u

git commit -m "Updated Wordpress from version 3.x to version 3.y

Checkout the plugins branch and merge the core changes
```
git checkout plugins
```
```
git merge core
```
Checkout the master branch and merge the core changes from plugins
```
git checkout master
```
```
git merge plugins
```

Copy your wp-settings files saved in step 1

cp ~/wp-settings/.htaccess .

cp ~/wp-settings/wp-config.php .

Applying language updates

Run the language update script found in the wordpress-tools package:
```
wp_update_lang_files midd
```
cd into your WordPress development directory
Add the updated language files
```
git add .
```

Commit the new language files

git commit -m "Updated language files to latest version."

Applying plugin updates

Moved into Confluence

Logging WordPress changes

Record changes to the Changeblog by either:

git log [master SHA-1]..HEAD | changelog WordPress

or

Submit to the ChangeBlog

Theme Update Checklist

Themes are updated in using the same process as plugins, however we need to make sure that the look and feel does not change significantly and that widget areas to not loose content due to changing widget region ids. For each theme that is to be updated check 2-3 of the sites using it against the following checklists.

Use this checklist to determine if there is a "significant" change to the theme. If all of these items are the same for standard desktop-sized browsers (1280 x 1024) then we can reasonably say that the theme has not significantly changed. Responsive themes may radically alter the design for small screens. This is to be expected and encouraged.

Is the color scheme the same?
- Is the text color the same or a very similar shade?
- Is the background color behind the text the same or a very similar shade?
- is the overall background color the same or a very similar shade?
- Are border colors & weights the same or a very similar shade?
- Are sidebars, headers, and footers the same color or a very similar shade?
- Is there a background graphic, and if so is it the same?
Is the text treatment the same?
- Is text about the same size (within 2-3 points of each other)
- Is the font of the same family (serif versus san-serif)?
Are menus and widget regions the same?
- Are menus and regions in the same place?
- Are menus in the same location (top, left side, right side, etc)?
- Do menus have similar drop-down/expand behavior?
- Are widgets/sidebars in the same place (top, left side, right side, etc)?
- Are widgets/sidebars the same size (within ~30px of the original height, width, padding)?
Is the header image similarly sized and located?
Are comments styled similarly (same text size, color, location)?
Are tags/categories still shown and similarly styled (size, location, color)?
Does the theme generally look the same to you?

Theme updates for which the answers are "yes" to all of the above may be applied without notification to site administrators/editors. If the answer is "no" to any of the above, then the updates will be held off until we have a chance to notify site administrators/editors and work with them to find an acceptable replacement theme or confirm updates to the current theme. In extreme cases, the JetPack CSS editor can be used to override the new theme styles to emulate old versions of a theme.

Additionally, verify that all widgets are retained in their same widget areas. If not, widget area ids may have changed. This is a technical problem for which we can either manually replace widgets if only a few sites use the theme or script a fix if many sites use the theme. No themes should be updated in such a way as to leave sites broken for more than a few minutes while the updates are being applied.

Plugin and Theme Security Reviews

All plugins and themes should be reviewed for vulnerabilities detailed in the WordPress Plugin Security Review Checklist.

When adding new plugins, be sure to add documentation to the Help:WordPress_Plugins page.

Library & ITS Wiki