You've decided to subtheme your site. Huzzah! But, it's quite possible you're never done this before and you're not even sure what that means or where to begin. Making the decision to be a Site Builder and create custom elements for your site is a significant undertaking, but we want to give you a brief overview of what's involved in the workflow process to help you get started.

What this article does cover:

• The best practice workflow and outline
• A description of the major points of the workflow
• Links to resources to explain these points in more detail and help you learn
• A PDF download of the Development Workflow for Subthemers (as seen below)

What this article does not cover:

• Step-by-step instructions on how to sub-theme

 

Getting Started

Initiating your subtheming process means setting up your working environments. This will include setting up a local development environment on your personal computer, creating accounts with GITHub and Bitbucket, and acquiring a Site Builder role for Site Factory where your sites are hosted if you haven't completed this last step already.

You and Your Team

To begin, each of you will need to set up your local development environment on your work computer. The popular 'stacks' (a collection of software comprised of a database, server, terminal, object-oriented programming language (PHP)) include:

• MAMP - Apache, MySQL, PHP for Mac
• WAMP - Apache, MySQL, PHP for Windows
• LAMP - Apache, MySQL, PHP for Linux
• Docksal - a multi-platform-friendly stack

You will also need a Database Management application. The SiteFarm team uses Sequel Pro, but as this is a licensed software product for the Mac OS, it might not be an ideal solution for you and your team.

All operating systems include a Terminal command line application, which will be an essential tool when writing certain processes and committing your code.

Finally, you will need a Code Editor. You may already have a favorite, so continue to use that especially if it integrates well with Git, PHP, and Drupal in general. If you haven't used one yet, here just a few suggestions for software, but do your own search for 'code editor applications' to find a good fit for your needs.

• Atom (Free, multi-platform [see their downloads page])
• Brackets (Free, multi-platform)
• Notepad++ (Free, Windows)
• VSCode (Free, multi-platform)
• Sublime Text (Multi-platform, license)
• PHPStorm (used by the SiteFarm team, license, multi-platform)
• BBEdit (license, Mac OS)
• UltraEdit (license, multi-platform)

Once you have the software installed, you will then sign up for Git and install it on your computer.

GIT

What is Git? 
Git is a version control system for tracking changes in computer files and coordinating work on those files among multiple people. 

Why use it? 
It's a safe way for one or many people to code a project with minimal risk and maximum redundancy in the form of version control. A team can have a production branch, a development branch, and then individual branches representing new projects or isolated bits of code one person is working on, safely away from what others are doing. Once the work is done, an individual branch can be committed back to the development branch and tested. If the test is successful, the team can then prepare to merge the development branch with their production branch and deploy that to their site(s).

Link: https://git-scm.com/
Training documentation: https://www.atlassian.com/git/tutorials/learn-git-with-bitbucket-cloud
Visual User Interface application for users not comfortable with the Terminal command line: SourceTree

Bitbucket

What is Bitbucket?
Bitbucket is a web-based version control code repository hosting service owned by Atlassian, for source code and development projects that use either Mercurial or Git revision control systems.

Why use it?
It's a powerful code repository that will allow you to refresh more than one site at a time. Are you a large organization with more than ten sites? Can you imagine creating a significant theme upgrade and having to update each site manually? Using Bitbucket in conjunction with Site Factory means you can do an auto-refresh on all your sites at once.

Link: https://bitbucket.org

Site Factory

Your sites are hosted with Acquia Cloud Site Factory, a centralized site management system on which we run SiteFarm.

Each site has a "Manage site theme repository" option that allows you to configure a connection to your Bitbucket account. Once you have completed your subtheme work locally and are ready to test it in a site in the Site Factory, you'll want to use this connection to push your subtheme to your site. From there, you'll be able to enable your subtheme in your site's Appearances tab.

To help you develop and maintain your production websites, you can create site collections, which bundle and organize related websites. A site collection contains a primary website (to which you can associate a custom domain name) and one or more secondary websites for in-progress development.

Next Steps

After you have reviewed this workflow, explored the documentation and tutorials provided for Git, Bitbucket, and Site Factory, and set-up your local work environment, you will be better prepared for the four-part video series on subtheming created by our graphics designer, Anthony Horn, which will cover the process in more practical, hands-on terms.

Begin the video series by continuing on to our Vimeo video location.