Are you using the Drupal Spec Tool? Because if you aren’t, you should be.
I mentioned it in passing during my webinar a couple of weeks ago and I saw someone say… “How did I not know about this?!” It got me thinking that a post might be well worth it on this topic, because maybe it’s not on your radar either. This post is all about the Drupal Spec Tool and how to integrate it into your workflow!
Oh and did I mention it’s both free and open source?
“This project provides a tool for specifying Drupal architecture details and generating automated tests for them”
What is the Drupal Spec Tool?
So what is the Drupal Spec Tool? The official description from the project is: “This project provides a tool for specifying Drupal architecture details and generating automated tests for them. It consists of 1) a Google Sheet for capturing specification and generating tests from it and 2) the Behat contexts that automate the generated tests (examples).”
This sounds much less exciting than it actually is. It’s a really awesome spreadsheet! Wait, that also sounds not very exciting.
The spec tool lets you define every content bundle (node, media, taxonomy, block, etc.) that you are going to use on your project. Then it lets you define every field you’ll build out for that bundle including all the nitty gritty details required for site building (like widget type, target reference, if it’s required or not, helper text, etc.). You can also specify all of your views, workflows, workflow transitions, role and permissions, and basically anything / everything else you might want to task a site builder to do. It even has the ability to automatically generate relationship diagrams between your bundles AND Behat tests!
Why should you use it?
One of the biggest challenges I’ve experienced with Drupal on long-running builds is keeping track of decisions related to content architecture.
Should that field be on all of the content types? Or just this one.
Did we decide that we were always going to use this widget for that field? Or did we decide that in this context it should be different.
I thought that field should be unlimited cardinality? When did that change?
As a Drupal site evolves over time and your tickets / stories gradually get completed and closed, it can be really challenging to keep track of the decisions being made in real time as they relate to your content architecture. I’m pretty good about documenting architectural decisions for big things like integrations, workflow, custom modules, etc. But field level tracking? That can be really challenging when you have a dozen content types and a TON of fields !
Enter the spec tool. The spec tool gives you a place outside of Drupal to define your content architecture, map out what’s been done and what still needs to be done. You can also track things that have been removed (just to keep a record).
More importantly, you can (and should) use the spec tool as the source of truth for your site building. On my builds I usually do the following:
define my content architecture in the spec tool
refer to the spec tool in my acceptance criteria / implementation details on each ticket / story so the developer(s) build to the spec
ask my QA team to utilize the spec tool to compare expectations with reality
ask my product owner to utilize the spec tool during UAT
The end result is that everyone is using the spec tool as the source of truth. If something changes, the spec tool changes to stay in-sync with that change. At any given point, everything in the Drupal site always matches the spec tool.
How Do you Use it?
The spec tool starts out as a Github repository. But if you follow the link it will create a new Google Sheet for you to copy for your project:
From here, someone (usually the architect) should start filling it out and defining all the necessary requirements for the site build.
Your bundles and fields are defined on separate tabs:
The template comes with all the bundles and fields that ship out of the box with Acquia Lightning, so if you’re using Lightning you have that much done already! If you aren’t using Lightning you can just reference how to use it, then delete out that content and start fresh.
The spec tool also gives you a summary of how many things you’ve defined vs. built out. So if you’re using it up front to define your content architecture and keeping it up to date during implementation, then it will help you keep track of how much of your work is left to do.
Finally, don’t forget about the Behat tests and entity relationship diagrams.
The last piece of this that can be overlooked is including the spec tool in your project’s composer.json file. This may seem silly! However, if you’re taking advantages of the Behat testing, you’ll need the proper contexts defined so that the tests can properly run.
"acquia/drupal-spec-tool": "^3",OR
"acquia/drupal-spec-tool": "^4",Remember, the 3.x version is for Drupal 8.x and the 4.x version is for Drupal 9.x. If you don’t plan on using the Behat features from the spec tool you do not need it in your composer.json file.
In Conclusion
The spec tool is one of those things that represents a bunch of work “you’re probably already doing anyway.” So integrating it into your workflow shouldn’t be a significant amount of effort. Granted, if you’re maintaining a site and/or most of the way through a build there may be some retrospective work required to go back and build out the spec. But I assure you, it’s well worth the effort.
There is a golden rule however, and I urge you to follow it. As with so many things in Drupal (like configuration management strategy and dependency management) it becomes significantly less useful if you only adopt it half way. If you’re going to write a source of truth for your content architecture, then make sure you:
keep it up to date
use it throughout your team / process (don’t let the developers go one place and product owners go someplace else).
Finally, a quick shoutout (and thanks) to Travis Carden for creating and maintaining the spec tool. Much like my must have Drupal modules, this is something I use daily on every single Drupal project I take on. I hope you integrate it into your workflow(s) as well! It’s one of the most valuable companions to Drupal out there today.