Problem/Motivation
User story:
As a contributed module/theme maintainer, I want to know whether the composer.json file in my project repo conforms to Drupal.org best practices, so that I can spend my contribution time working on code instead of puzzling over what I should put in or leave out of composer.json.
The official composer.json schema documentation lists the fields in the composer.json schema. It declares name, description as Required; license, authors as "Optional [...] but highly recommended"; and the rest of the fields as Optional.
Projects accessed through packages.drupal.org go through a Drupal.org component called the
Drupal.org Composer Service (façade) a.k.a. project_composer →
, which sets some release metadata and sets/overrides some composer.json fields (i.e.: keywords, homepage, version, license, authors, support, type, and package name). This ensures that Drupal.org projects will work when accessed through packages.drupal.org, even if they don't have a composer.json file committed to the repo.
As a project developer, the Drupal.org Composer Service is pretty handy, because some of the fields it writes for me are tedious/error-prone to update myself (e.g.: authors, keywords, version, type), or out of my control (e.g.: license, name, and the URLs for the homepage, support which could change if the d.o maintainers change pathauto patterns). Plus, for simple projects that only use the Drupal APIs, I don't really want to have to worry about writing a composer.json.
However, some projects depend on libraries and projects not hosted on Drupal.org... in that case,
the docs say that a module developer needs to Add a composer.json file →
.
The docs on the
Add a composer.json file →
page provide an example composer.json, but the example contains schema fields that the Drupal.org Composer Service already fills in if you don't specify them. Also, Drupal.org provides a
Lenient Composer Endpoint →
and thus,
the docs say "It is better not to provide a drupal/core version requirement in composer.json" →
, which may not be obvious to new project maintainers (especially if they come to Drupal from the wider PHP ecosystem).
Thus, as a project maintainer, if I do have to maintain my own composer.json, it is possible for me to add things to it:
- that will cause Drupal.org problems (e.g.: the wrong
name, the wrong license),
- that will cause problems for me (e.g.: define a "repositories" entry for
packages.drupal.org/7 for a D8 module), and/or,
- that might work fine for my site, but would cause issues for others (e.g.: a dependency on
drupal/core, drupal/core-dev, drupal/core-recommended, or mglaman/composer-drupal-lenient)
- (note it is also possible for me to commit invalid JSON in
composer.json, but I believe this is already caught by an existing linter in the pipeline - eslint?)
Given that we already have linters for JSON, YAML, CSS, JS, PHPCS, PHPStan, etc., that run in
GitLab CI for contrib modules →
it would be an awesome developer-experience improvement if there was a Drupal.org-specific composer.json linter.
Proposed resolution
Create a Drupal.org-specific composer.json linter that would be able to identify the following issues:
- Specifies a
name that is not the project's machine name.
- Specifies a
license that is not GPL-2.0-or-later.
- Specifies a
version or time, since those will be added by the packaging script.
- Specifies
keywords, homepage, version, authors, or support, which the Drupal.org Composer Service can write for me.
- One or more of the following (not sure which of these makes the most sense):
- Adds a "repositories" entry for
packages.drupal.org or packages.drupal.org/lenient.
- Adds a "repositories" entry for
packages.drupal.org/7 if I'm writing a D8+ module.
- Adds a "repositories" entry for
packages.drupal.org/8 if I'm writing a D7 module.
- Adds a dependency on
drupal/core, drupal/core-dev, drupal/core-recommended, or mglaman/composer-drupal-lenient
... and then when it's working, follow up with an issue to the
GitLab Templates project →
to add it to the GitLab CI pipeline for contrib modules.
Remaining tasks
- Determine how/where to build the linter (in PHP? in JS? As a PHPCS sniff? As an ESLint rule? Something else? Warning: bike-shedding / The Law of Triviality is likely to apply here)
- Build the linter
- Create an issue to the
GitLab Templates project →
to add it to the GitLab CI pipeline for contrib modules
User interface changes
To be determined.
API changes
To be determined.
Data model changes
To be determined?