Getting from GitHub to WordPress
Maintaining an open source project as big as jQuery requires the use of various software and services. Two of the products we rely on and enjoy the most are GitHub and WordPress.
We’ve been using and loving Git and GitHub for years now. The community collaboration has been phenomenal. We’ve seen a massive uptick in community-provided bug fixes, refactors, new features, etc. Even within the team, the services provided by GitHub have provided a huge productivity boost. Forks and pull requests provide a great mechanism for sharing code and peer code reviews. The interface renders almost every file exactly how we want it to, especially Markdown. The API and service hooks provide a great way to automate various tasks.
Even longer than we’ve been using GitHub, we’ve been using WordPress to manage our various web sites. We have a surprisingly large number of them. Between project sites, API documentation, tutorials, contribution guides, events, and organization sites, the number of web sites we maintain rivals the number of code projects we maintain. WordPress provides tools which make managing this many sites with a common brand almost as simple as maintaining just one site with shared users, theme inheritance, and a great plugin architecture, providing even more hooks than GitHub.
The missing pieces
Unfortunately, our WordPress experience lacked all the collaboration tools and workflow we love. Only a few people had access to edit content, and collaboration without pull requests is painful. Managing content on api.jquery.com was an even bigger hassle because of our XML based workflow, which the WordPress editor clearly wasn’t designed for.
While GitHub has tons of tools that we love, and they even have GitHub Pages, it lacked the infrastructure we need for managing our site content. GitHub Pages have no built-in features and can’t have any server-side processing. Features like search and commenting either need to be added per site via client-side JavaScript or can’t be implemented at all.
Bringing it all together
In order to resolve these issues, we decided to find a way to bring these two products together and get the best of both worlds. It started off pretty bumpy, but we managed to do just that! Things started to really pick up when we got the support of WordPress’ Lead Developer Andrew Nacin. Nacin played a key role in getting our new infrastructure set up and ensuring we were using WordPress as efficiently as possible. With his help, and the help of a few new projects – such as node-wordpress, grunt-wordpress, and grunt-jquery-content – we were able to build exactly what we wanted.
We now manage our WordPress theme in jquery-wp-content, and the content for all of our sites are stored and managed in individual repositories on GitHub. Storing the content of each site on GitHub gives us all the benefits of tracking tasks in issues, discussions on pull requests, visual diffs for changes, etc. The content of each page is generated by grunt-jquery-content from HTML, XML or Markdown source depending on the repository. This content is then synced to WordPress using grunt-wordpress. Just like our code, all of our site content is open source and released under the terms of the MIT license, with the exception of our branding which is not licensed for use by others.
We’re now powering a dozen and a half sites with this new process, averaging 20 contributors per site. Our most popular sites for community contribution are learn.jquery.com which is nearing triple digits and api.jquery.com which currently has 50 contributors. We’re averaging 40 pull requests per site as well, showing just how beneficial this new workflow has been for the team and the community. If you’d like to join in on this community effort, you can read more about our process and how to get involved on our contribution site and help make jQuery better for everyone.