Tech News

As someone who has been building Drupal sites for over 12 years now, I'd like to think that my knowledge and expertise has grown at a rate similar to the power, flexibility, and complexity of the Drupal project itself. For well over 10 years, Drupal training and development has been the focus of my consulting business; over the holidays I took some time to look back and really think about the lessons I've learned and how I can utilize them moving forward. 

In addition to documenting the process for myself as well as my current and future clients, I also wanted to share what I've learned with the Drupal community. After all, it is this community that has made it possible for me to have the success that I have found so far. I have worked on projects of all sizes from large Fortune 500 companies to small local businesses. I’ve been alone on project as well as with large teams of developers. There have also been projects with massive budgets as well as projects with no budget. The breadth of this experience has really contributed to my ability to provide more value for my clients. 

One word I use often when speaking with current as well as prospective clients is "sustainability". I always want to be involved in a solution that provides good value not only now, but for the lifetime of the project. I want to build sites that are easy to maintain, easy to update, and easy for different developers to cycle in-and-out of. With sustainability, and all of the elements that contribute to it in mind, I present the 11 tips to start a Drupal project right. 

Having a professional developer workflow should go without saying, but I often come on-board small, single-developer projects that have a remote development environment and a live environment - and nothing else. At the very least, projects of all sizes should have not only a dev and live environment, but developers should have local environments as well. 

There's a lot of focus on DevOps in the Drupal ecosystem (with good reason), but before you jump into a continuous integration/continuous development (CI/CD) system, be sure you have the basics first and then add complexity only as necessary. I've seen way too many projects invest in a full-on CI/CD system only to have it ignored because developers didn't have the time and/or expertise to utilize it properly.

This is a bit of a pet-peeve of mine. I'm a firm believe that commitment to a project tracker must include 100% of the development team and stakeholders. Note the "and stakeholders" - this includes project managers, content and QA folks, and anyone else who has a role in the project. How often is a project ready to launch and then at the last minute a stakeholder chimes in requesting changes? This is demoralizing and frustrating for the entire development team.

Project tracker tasks should be focused. Large tasks like "theme the site" aren't very helpful and comment threads in tasks like this often become unwieldy, defeating the purpose of using a project tracker. Train the entire team on using the project tracker and committing to using it for the majority of project task communication. 

You're not using Git yet? Seriously? Stop reading this and go get yourself and your team trained up (we offer training). Also - commit early and often. Smaller, more focused commits (like project tasks) are easier to manage.

This is an article about Drupal 8, so this isn't really optional. While there is work in the community on various Composer-related projects, for now the Composer template for Drupal projects is the de-facto standard for managing your Drupal 8 project's codebase. Don't know how to use Composer? Learn it (we also offer Composer training).

Avoid "it works on my machine" conversations for the rest of your life by ensuring that the entire development team is using identical local environment configurations. Docker-based solutions are tailor-made for this type of thing, but it has been possible for awhile with virtual machine-based solutions as well. A solid local development environment will pay dividends - making it easy to get new developers up-and-running, and allowing developers to focus on building the project, not monkeying around with their local environment.

I've been a fan of DDEV-Local, a Docker-based solution, for awhile - I provide training and I also wrote a book about it! 

This is where I see projects go sideways more often than not. When defining the information architecture (IA) for the site, all stakeholders must be involved. This tip really goes hand-in-hand with the next one, but the bottom line is that this needs to be a discussion. There's nothing worse than getting near the end of a project and showing it to a content author and finding out that there are gaps. Generally, the goal is to get the granularity right when defining IA. This is next to impossible to do without feedback early in the process from all stakeholders.

Review any existing content that is to be migrated to the new system, ask content authors what the issues with their current system are, and be careful not to over-engineer a solution that won't provide enough bang-for-the-buck. 

This tip goes hand-in-hand with the previous one - an important part of defining the IA is testing and confirming that everything is accounted for. In my experience, the absolute best way to do this is by prototyping the system. Allow your actual content authors, editors, and admins to test-drive the new architecture by adding and editing content on a prototype of the site. This needs to be done very early in the development process, so the focus should be 100% on the add/edit forms - not the output. In fact, I recommend not putting any effort into theming the output at this point, making it crystal clear that the prototyping exercise is to confirm that the set of entities, bundles, and fields designs are on-target.

I really cannot stress enough how important this step is. IA mistakes made early that are not corrected will be a burden until they are corrected (if ever). It's normally relatively easy (and inexpensive) to fix IA mistakes early - quite the opposite if they are left to fester and other parts of the site are built upon them. I have never been part of a project where the IA prototyping didn't result in important updates to the IA. 

If you're building a custom theme, then you probably need a style guide. Part of a solid UX/UI design is consistency in design. Consistency brings user comfort. When users are more comfortable on your site, they'll spend more time there. 

Style guides can be as simple or as complex as they need to be. At the absolute minimum, I would recommend that a style guide contain basic typography and a color palette. You'll need to consider how/if typography will change based on responsive mode (are H1s the same pixel size on mobile as they are on a desktop display?) Similarly, you'll want to think about how the header/navigation/footer respond to various screen widths as well. Have an element that appears throughout your site? Then define rules how it looks in various places and various screen widths. 

Similarly, if your project is going to have a custom theme, then you're going to need to design the layout of key pages. How are landing pages arranged? How do they respond at various screen widths? Think about the entire site and design wireframes for a representative sample of pages. Only 2 or 3 wireframes are necessary for many projects (home page, content page, interior landing page). 

Consider these representative pages as a group, not individually. Look for common elements (easier to theme) and value consistency. If every page is a one-off, then implementation costs will rise. 

Start with wireframes and generate only the mockups you need. Often, between a solid style guide and some good wireframes, mockups aren't necessary in many cases. Think of the style guide as a box of LEGO bricks that can be assembled into mockups in various configurations. If time and budget is limited, favor the style guide over mockups.

Drupal 8's configuration system provides a powerful tool to easily push non-code configuration changes between environments. The "trick" to using it is that the entire team has to understand and participate in the process. If the development team is five people, and only two are using the configuration system, you're going to have rough sledding. 

The configuration system will help enforce a solid developer workflow, encouraging team members to update and test configuration (like a new View) locally before pushing it to remote development environments. A byproduct of using the configuration system is that config changes can easily tracked by the project tracker via commit messages. 

There's not much that kills developer morale and confidence in a project more than lack of project leadership. At the core of this is often a lack of project planning and milestones. All team members should be involved in the setting of goals and milestones for the project. A single milestone of "the site must be done in 5 months" doesn't cut it. The entire team should work together to define realistic and meaningful milestones. Take into account non-project responsibilities of team members, identify and plan for potential pain points in the project. 

Project leaders need to listen to team members and provide training and professional guidance when necessary. Most developers are problem solvers who like to learn new things. Project leaders should embrace and leverage this for the betterment of their projects, the result will be a positive one for the entire team!

Mike Anello is the architect and instructor for DrupalEasy’s Drupal Career Online, which includes intensive live online sessions, rich learning resources, an active learning community and hands-on projects designed to provide those who need to get skilled up in Drupal with the best possible start. The next session of the DCO starts February 25th. If you’d like to learn more, you can sign up for a no-cost Taste of Drupal mini-webinar.

If you build Drupal 8 sites using the Drupal Composer/Drupal Project Composer template (DCDP), then you've likely noticed the development dependency webflo/drupal-core-require-dev. If you're like me, you probably didn't give it much thought the first 20 or 30 times you used the template. 

After a while though, I started to dig deeper into the details of DCDP, wanting to be able to understand exactly how it worked and what customizations I may want to make. DCDP was really my first real exposure to Composer, and the more I learned, the more I wanted to learn (as is often the case). My curiosity led me to this drupal-core-require-dev rabbit hole.

First, let's level-set ourselves - when you run either "composer install" or "composer create-project" (which is actually calling "composer install" as well) without the "--no-dev" switch, Composer will install all dependencies listed in your composer.json file in both the "require" and "require-dev" sections (as well as dependencies of dependencies). If you take a look at DCDP, you'll notice that in the "require-dev" section, there is one entry: webflo/drupal-core-require-dev. 

So, as most folks who start Drupal 8 projects using the recommended DCDP command listed in the README (composer create-project drupal-composer/drupal-project:8.x-dev some-dir --no-interaction), Composer is installing everything in the "require" and "require-dev" sections - including webflo/drupal-core-require-dev.

What exactly is webflo/drupal-core-require-dev? Well, it is a "virtual" dependency - meaning it doesn't include any code, rather it just includes a composer.json file that specifies the specific versions of Drupal core development ("require-dev") dependencies that are used to run Drupal core tests. The interesting (and sometimes problematic bit) is that webflo/drupal-core-require-dev doesn't specify any versions for non-development ("require") dependencies. If you take a look at Drupal core's composer.json file, you'll see that for the most part, specific versions of dependencies aren't specified - rather a range is. 

This leads to the situation where a project built with webflo/drupal-core-require-dev could have different dependency versions (as long as they adhere to the version constraints is Drupal core's composer.json) than what comes with Drupal core if you had just downloaded it from drupal.org.

For example, if on the date version 8.7.0 of Drupal core was released one of the development dependencies was at version 1.3.1, then that is the version that is provided with Drupal core 8.7.0 downloaded from drupal.org regardless of when you download it. But, when using the DCDP as-is, if since the release of Drupal core 8.7.0 the development dependency was updated to 1.3.2, then when the project is installed using "composer create-project", your project will be using version 1.3.2 of the dependency. While this seems minor, it has led to some issues. 

Also - be aware that there are different versions of webflo/drupal-core-require-dev for every minor version of Drupal core. So, if you're updating your site from Drupal core 8.6.x to 8.7.x, then you must also update to webflo/drupal-core-require-dev to 8.7 as well. This is the reason the update command for DCDP includes webflo/drupal-core-require-dev:composer update drupal/core webflo/drupal-core-require-dev "symfony/*" --with-dependencies

After learning this, I had an obvious question: what's the advantage of having Composer install updated versions of Drupal core dependencies? The only thing I found was that if you're a core or contrib developer, then it would be useful to know if your code breaks using updated dependencies. I'm hard-pressed to think of another reason when this makes sense. For most Drupal 8 projects, I think it would be beneficial to use the exact dependencies that the particular version of Drupal core ships with. This way, we can be 100% certain that our project has the same dependency versions that the community's testing infrastructure has validated for the particular version. Luckily, that's what webflo/drupal-core-strict is for. 

It works almost the exact same way as webflo/drupal-core-require-dev except that it includes exact versions for all dependencies of Drupal core - for both development ("require-dev") and non-development ("require") packages. The exact versions are the ones that have been tested and are included in the "official" version of Drupal core (for each minor version) downloadable from drupal.org. Like webflo/drupal-core-require-dev, there is a minor version of webflo/drupal-core-strict for each minor version of Drupal core.

So, why does DCDP use webflo/drupal-core-require-dev? Well, there's some debate about if it should or not. 

As a side-note, if you host on Pantheon, and use their Pantheon-flavored version of DCDP, then you're probably already using webflo/drupal-core-strict.

First, the bad news - if you want to start a new project using webflo/drupal-core-strict, you can't use DCDP out-of-the-(virtual)-box. But, there's a couple of possibilities. At first glance, it seems that you could fork DCDP, make the relevant change to webflo/drupal-core-strict in the composer.json file, then use "composer create-project" on your fork. But, this would also require posting your fork on Packagist (which is discouraged), updating your fork's README (for the create-project and update commands) as well as keeping your fork up-to-date with any DCDP updates. I wouldn't recommend this method.

A better option is to use the "--no-install" option of Composer's "create-project" command:

1.  Use the recommended command on the DCDP page, but add a "--no-install" at the end of it:

This will download DCDP to your local, but not install dependencies. 

2.  Edit the composer.json file with:

• New project name
• New project description
• Remove "webflo/drupal-core-require-dev" from the "require-dev" section
• Add "webflo/drupal-core-strict": "^8.7.0", to the "require" section (ensure the version matches drupal/core).
• Change the version requirement for drupal/console to: "drupal/console": "^1.0", (to avoid version conflicts)
• Change the version requirement for drush/drush to: "drush/drush": "^9.0", (to avoid version conflicts)
• Remove "composer/installers" from the "require" section (it is already specified in webflo/drupal-core-strict). 

3.  Run "composer install". 

You'll need to remember that when you want to update Drupal core, you'll want to use the following command (instead of what is in the DCDP README):

If you're not crazy about either of these two options, there is a third (future?) - leave a comment on this issue and ask for webflo/drupal-core-strict to be used in DCDP. 

What if you already have a project based on DCDP and you want to change it from using webflo/drupal-core-require-dev to webflo/drupal-core-strict? Here's some possible ways of doing it:

As always, to be safe, please test things like this on a copy of your project.

This is definitely a tedious process. It involves first removing webflo/drupal-core-require-dev using:

Then, attempt to require drupal-core-strict:

Depending on a number of factors you're likely to get a bunch of "Your requirements could not be resolved to an installable set of packages." messages. How many you get is mostly a result of the length of time since the previous minor release of Drupal core - the longer it has been, the more dependencies have probably been updated. For each dependency listed, you'll need to downgrade it using something like:

What is happening is that webflo/drupal-core-require-dev allows dependencies to get upgraded outside of the Drupal core release timeline, while webflo/drupal-core-strict does not. So, you'll need to downgrade dependencies that have been updated. You'll have to do it one-at-a-time - try requiring webflo/drupal-core-strict, see the error message, downgrade the offending dependency, then repeat. In some cases, it isn't immediately obvious which dependency needs to be downgraded, or which version it needs to be downgraded to, so be prepared to use the "composer depends" command a few times. 

Eventually, requiring webflo/drupal-core-strict will succeed and you'll know that you're done.

There is one major downside to this method though - by requiring specific versions of each dependency, the versions are effectively pinned in the composer.json file. So, the next time you update Drupal core (and webflo/drupal-core-strict), these specific version constraints will conflict with the updated webflo/drupal-core-strict. One solution would be to remove all of these dependencies from the "require" section of your composer.json file. 

If Method one is tedious and precise, then this method is more of a (less tedious) big hammer. Depending on the complexity of your codebase, this might be a better option for simpler projects. In short, make a copy of your composer.json (for reference), then use "composer remove" to remove dependencies on drupal/core, webflo/drupal-core-require-dev, and anything that depends on them. Then, use "composer require" to add back drupal/core and webflo/drupal-core-strict: 

Then, add back (composer require) all the dependencies you had to remove. Be sure to add back the same versions of each dependency (this includes Drupal profiles, modules, and themes!) to end up where you were when you started. Once everything is back, then you'll probably want to "relax" the version constraints of your dependencies in your composer.json by adding a "^". For example, if you re-add a contrib module using:

Then in the "require section" of your composer.json you'll have:

This will prevent drupal/pathauto from being updated. So, you'll want to change this to:

While researching this topic, I posted an issue in the webflow/drupal-core-require-dev queue and Greg Anderson was kind enough to offer another method:

[One] solution is to modify your composer.json file, attach the same version limit to drupal/core and drupal-core-strict (e.g. ^8.7.3) to limit what [composer update] needs to look at, and then [delete] both your composer.lock and your vendor directory and run "composer update".

One caveat about this method is that it will update everything. Any outstanding dependency updates (including Drupal profiles, modules, and themes) will be applied (unless you constrain them in your composer.json). Here's what Greg suggests:

• Pin your contrib modules that are not updated to an exact version in composer.json.
• Remove vendor and composer.lock, add webflo/drupal-core-strict [to your composer.json], and generate a new lock file [with "composer update"].
• Remove the pins of your contrib modules in your composer.json by adding ^ [similar to the example in the previous method.]
• Run composer update --lock

Is there an easier way to do this? If so, I'd love to hear about it. Let me know in a comment below.

So which one should you use? If all your contrib projects are up-to-date, then I'd go with Method 3. If not, then I'd recommend Method 2 or 3 depending on which you're more comfortable with.

Of course, in the future, much of this may be moot (for new projects, at least), as there is an active effort to bring an official version of DCDP to Drupal, including a new scaffolding dependency (committed to drupal/core on July 10, 2019!) and something akin to drupal-core-require-dev and drupal-core-strict. To find out more, check out the Composer Support in Core Initiative. 

Thanks to Greg Anderson, one of the Composer in Core Initiative coordinators, for his input and review of this article.