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:

 help                                 Displays help for a command
 list                                 Lists commands
cache
 cache:clear (cc)                     Clears caches
ci
drupalci
 drupalci:list (ci:l)                 Lists test results for an issue
 drupalci:watch (ci:w)                Watches a Drupal CI job
issue
 issue:apply                          Applies the latest patch from an issue.
 issue:branch                         Creates a branch for the issue.
 issue:interdiff                      Generate an interdiff for the issue from local changes.
 issue:link                           Opens an issue
 issue:patch                          Generate a patch for the issue from committed local changes.
maintainer
 maintainer:issues (mi)               Lists issues for a user, based on maintainer.
 maintainer:release-notes (rn, mrn)   Generate release notes.
project
 project:issues (pi)                  Lists issues for a project.
 project:kanban                       Opens project kanban
 project:link                         Opens project page
 project:release-notes (prn)          View release notes for a release
 project:releases                     Lists available releases
tci
travisci
 travisci:list (tci:l)                Lists Travis Ci builds for a Drupal project
 travisci:watch (tci:w)               Watches a Travis CI job
 

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.