DrupalEasy: cspell and drupalorg CLI: two useful tools for Drupal contrib module maintainers

While preparing the recent Markdown Easy 1.0.1 release, I utilized a couple of tools that I hadn't used before in order to help improve code quality as well as the quality of the release notes.

cspell

cspell is a Node.js spell-checker for code that was made available to the default Drupal GitLab templates in February, 2024. There is a new SKIP_CSPELL variable that can be set if you'd like your project to completely ignore cspell (it is enabled by default.) Documentation on using cspell in Drupal GitLab pipelines is available. I'd wager that most Drupal contrib maintainers will have the need for a custom word list (as I did,) so I took a few minutes to learn a bit more about it.

Cspell uses its default wordlist along with a few add-on dictionaries related to Drupal development (anecdotally, words like "mglaman," "gloop," "skynet," and "vampirize" are included) for checking the spelling of both variable names as well as code comments, but luckily, additional words (and patterns) can be added on a per-project basis in order to achieve a clean cspell report in GitLab pipelines. While there are several methods to add a list of custom words, the way I felt was most elegant (and easy for me to remember in the future!) was to add a .cspell-project-words.txt file on the project root (in this case, the contrib module is the project.) This file then includes a list of words that cspell should not flag as misspellings. For the Markdown Easy project, I went with "Anello," "~commonmark," and "~ultimike" (possibly for obvious reasons.) The ~ modifier indicates those words are case-insensitive (additional modifiers are available.) With that change, Markdown Easy now earns a passing score from the cspell pipeline. 

drupalorg CLI

drupalorg is a command-line interface maintained by (who else?) Matt Glaman. I actually learned about this tool a few years ago after Matt blogged about it, but for whatever reason, I only thought about installing and (finally) using it recently. The general idea is to provide a command line tool for contributors to interact with drupal.org. It's available commands are:

The maintainer:release-notes command is especially helpful to automatically generate release notes for a new version of a Drupal contrib project. Here's how I installed and used this tool to generate the release notes for Markdown Easy 1.0.1:

1. I downloaded the drupalorg.phar to a new ~/sites/drupalorg/ directory on my local, and renamed the file to just drupalorg.
2. I then gave execute permission to this file via chmod u+x ~/sites/drupalorg/drupalorg

3. I use zsh, so I added the following to my ~/.zshrc file and then restarted my terminal:

   # drupalorg command line tool export PATH="/Users/michael/sites/drupalorg:$PATH"
4. Here's the important part - I then navigated to my local, working copy of the Markdown Easy module. In my case cd ~/sites/d10/web/modules/contrib/markdown_easy 
5. I then ran the following command to generate the release notes: drupalorg maintainer:release-notes 1.0.0  

I assumed at first that I should use the current release (1.0.1) as the argument, but after reading the documentation, I discovered that the command will generate release notes from the tag provided in the argument.

I also originally assumed that the command would take a contrib module's machine name as an argument, but after a few minutes of poking around the documentation, I realized that the command must be run from the module's directory.

You can see the automatically generated release notes here.

Summary

Both of these tools were rather easy to implement (once I read just a little bit of documentation) and seem like they'll be useful for just about any Drupal contrib maintainer.