Inheriting a Craft CMS Project: A Checklist

So, you just inher­it­ed a Craft CMS project…now what?

When you inher­it a new Craft CMS project, there are sev­er­al tasks you should con­sid­er to famil­iar­ize your­self with the project, its depen­den­cies, and require­ments. Not every­thing in this check­list will apply to you, but it should be a help­ful guide to mak­ing the project tran­si­tion successful!

The check­list is bro­ken up into two sections:

• Audit — this is the bulk of the work and where you’ll learn about the project, its dep­den­den­cies, per­cu­liar­i­ties, and, maybe, its shortcomings.
• Plan — With infor­ma­tion in-hand from the Audit sec­tion, you’re ready to make your plan for sta­bi­liz­ing or improv­ing the site.

We assume you already have access to the Craft CMS con­trol pan­el in the pro­duc­tion environment.

Audit #

This first step is all about infor­ma­tion gath­er­ing, so you know how the project was set­up, its cur­rent state, and any imme­di­ate work that might need to be done. This is where you’ll find out if you have an emer­gency or a project need­ing qual­i­ty, ongo­ing care.

TASK: Check the Sys­tem Report

Log into the pro­duc­tion sit Craft con­trol pan­el, if there is one, and look at the fol­low­ing from the Sys­tem Report (Util­i­ties > Sys­tem Report):

• Installed ver­sion of Craft CMS — how far is it from the most recent release?
• Installed plu­g­ins — How many are there? Typ­i­cal plu­g­ins or some with which you’re unfa­mil­iar? Are there any cus­tom plu­g­ins? Most rep­utable third-par­ty plu­g­ins will be in the Craft Plu­g­in Store.
• Are they any cus­tom mod­ules used in the project? 
• What is the PHP ver­sion run­ning on the pro­duc­tion server?

From this infor­ma­tion, you’ll be able to assess the state of the project quickly. 

• Is the project run­ning Craft 2 or 3? An upgrade is prob­a­bly need­ed soon. 
• Is the serv­er run­ning PHP 7? You’ll need to upgrade PHP before con­sid­er­ing a Craft 4 upgrade. 
• Does the project use a cus­tom plu­g­in or a mod­ule? This code will need to be updat­ed to upgrade to Craft 4. Mod­ule code lives with­in the project, but can you access the plu­g­in source code?

TASK: Find the project source code.

Ask your project con­tact if there is a Git repos­i­to­ry asso­ci­at­ed with the project, so you can clone the repos­i­to­ry and run the project local­ly (using DDEV, the offi­cial­ly sup­port­ed way to run Craft local­ly).

Sup­pose there is no Git repos­i­to­ry (which is com­mon, unfor­tu­nate­ly). In that case, you must down­load all of the code (minus the vendor direc­to­ry) and cre­ate a Git repository.

If you get access to the code, look for a README.md file for addi­tion­al project infor­ma­tion. A good README will include all project depen­den­cies, soft­ware stack, local devel­op­ment infor­ma­tion, and deploy­ment details.

TASK: Deter­mine if there’s a deploy­ment process.

This may be more dif­fi­cult to dis­cern from the serv­er or code, unless deploy­ment con­fig­u­ra­tion files are includ­ed in the project. You may need to rely on your project contact’s information. 

This might be a good time to move to a mod­ern devel­op­ment and deploy­ment work­flow for Craft CMS.

TASK: Deter­mine the host­ing situation.

You’ll want to deter­mine where the site is host­ed to answer the following:

• Is the host­ing suit­able for the site traf­fic and needs?
• Is the host­ing sup­port­ive of auto­mat­ed deployments?
• Is it shared host­ing? If so, you will want to move this to a reli­able, mod­ern host for Craft CMS.
• Check the Assets Filesys­tem (Set­tings > Filesys­tems) to deter­mine if the assets are stored on the serv­er or using a third-par­ty host­ing plat­form, like Ama­zon S3.

These checks will help deter­mine if you will keep the same hosting/​server/​infrastructure or if it’s time to change to some­thing more mod­ern and reliable.

TASK: Who man­ages or owns the Craft CMS license? Who man­ages or owns the Craft plu­g­in licenses?

A crit­i­cal part of main­tain­ing a healthy Craft CMS project is ensur­ing the Craft and plu­g­in licens­es are cur­rent. All plu­g­ins and Craft licens­es are man­aged through the Craft Con­sole, a web inter­face for man­ag­ing first- and third-par­ty Craft soft­ware licenses.

Find out who owns the licens­es and man­ages them. Is it the pri­or agency or devel­op­er? Is it the client? If you can­not find out, open a Craft CMS sup­port tick­et and inquire about the license own­er for each plu­g­in and for Craft CMS. You can access the plu­g­in licens­es from Set­tings > Plu­g­ins if allow admin changes is not dis­abled.

TASK: Check the templates

At this stage, you don’t need to do a deep dive into the tem­plates, but you should answer the fol­low­ing questions:

• Are the tem­plates using a frame­work (CSS or JS)? 
• Is there a design sys­tem that will make adding addi­tion­al pages or com­po­nents to the site easier?
• Do the tem­plates seem well-struc­tured and organized?

TASK: Check Users and Permissions

In this step, you want to con­firm that users with con­trol pan­el access still need that access. If not, revoke their access (but don’t delete the account, in case you need to revert access lat­er, and to pre­serve any con­tent authored).

TASK: Doc­u­ment Your Findings

Doc­u­ment every­thing you found dur­ing the pre­vi­ous steps, so you can use your find­ings to build a plan for any work required on the project.

Plan #

Now that you have done an audit of the project, you may know whether the project will be a sim­ple tran­si­tion to main­te­nance and updates or an infer­no of mul­ti­ple tech­ni­cal fires.

Now is the time to plan your next steps. What are your goals, as a devel­op­er, for this project? What are the goals of your client or customer? 

The details of your plan for the project will depend on what you find. 

• Is the project still run­ning Craft 2 or 3? You should build an update to the lat­est major ver­sion of Craft into the project plan.
• Does the site lack a mod­ern devel­op­ment work­flow? You should work that into your project plan and bud­get to quick­ly han­dle and safe­ly deploy future changes.
• Is the host­ing run­ning the project sub­op­ti­mal or over­pow­ered? Deter­mine the best host­ing for the project (which may or may not be your desired solu­tion). Some­times projects can be on over-spec’d and over-priced infra­struc­ture for the project’s needs.
• Are there per­for­mance or secu­ri­ty issues that need address­ing? Doc­u­ment what they are and put the fix­es in your plan.

Com­mu­ni­ty Ideas #

I asked the CraftQuest com­mu­ni­ty how they han­dle inher­it­ing a Craft CMS site. Here are some of the respons­es I received:

When you inher­it a new Craft CMS project, there are sev­er­al tasks you should con­sid­er to famil­iar­ize your­self with the project, its depen­den­cies, and requirements.

Not every project switch­es to a new devel­op­er because of a tox­ic fall­out. But even if that was the case, I’ve found that most devs are will­ing to give the per­son tak­ing over for them the ben­e­fit of the doubt.

So usu­al­ly my first steps are to get famil­iar with the code base and the deploy­ment set­up if there is any, all the gotchas that arise. Then I want to be able to han­dle Busi­ness As Usu­al requests as quick­ly as pos­si­ble. Then, depend­ing on the project qual­i­ty, I often need to do refac­tor­ing. Not just to make it a bit more ​“my own” so that I know where to find things and don’t spend min­utes try­ing to find a sin­gle tem­plate, but also to make it more future proof.

Big pic­ture, we have to work to get into the minds of the pre­vi­ous devel­op­ers — their build approach and code. The bet­ter we under­stand the site build, the bet­ter we can man­age expec­ta­tions, work­load, and make informed rec­om­men­da­tions. We appre­ci­ate that while we are inher­it­ing some­one else’s work, we need to be pre­pared to ​“own it” with our client’s best inter­ests in mind. This means we can’t always point fin­gers at the work of past devel­op­ers when things are chal­leng­ing and must bal­ance deliv­er­ing fix­es and enhance­ments in a way that is con­sis­tent with our busi­ness val­ues and process.