w3id.org

Appearance

meta/maintainer-github-username ​

Severity: warning · Status: enforced · Applies to: ids/**

What ​

Every identifier must record who maintains it, including at least one GitHub username.

It can go in .htaccess comments, in a README.md, or both. Either is acceptable — there is no requirement to have a README.md if the .htaccess comments carry the information.

This rule reads the whole identifier, so a record anywhere in it counts. meta/document-identifier-root is the companion rule that asks for one at the root specifically, since that is what claims the identifier.

A sub-directory may record additional maintainers for its own part of the tree, and several identifiers do. Those are read together with the root's, not instead of them — never move or delete a deeper record to satisfy either rule.

Why ​

This is the single most frequent review comment on this repository.

Identifiers are meant to last for decades, and the people maintaining them change. Without a contact:

  • a reviewer cannot tell whether a future pull request touching your directory is legitimate or a namespace hijack;
  • nobody can tag you to approve a change to your own space;
  • when your redirect target breaks, nobody can tell you;
  • when the service needs to reach identifier owners, you are unreachable.

A GitHub username specifically, because that is where changes to this repository happen. An email address alone does not let a reviewer confirm that the account opening a pull request is entitled to make the change.

Wrong ​

No contact information at all:

apache
RewriteEngine on
RewriteRule ^ https://example.org/ [R=302,L]

Contact information with no GitHub account:

apache
# My Project
# Contact: someone@example.org

RewriteEngine on
RewriteRule ^ https://example.org/ [R=302,L]

In .htaccess comments:

apache
# # /my-project/
#
# Permanent identifiers for the My Project vocabulary.
# https://w3id.org/my-project/ redirects to https://example.org/
#
# ## Contact
# This space is administered by:
#
# Firstname Lastname
# firstname@example.org
# GitHub username: exampleuser

RewriteEngine on
RewriteRule ^(.*)$ https://example.org/$1 [R=302,L]

Or in README.md:

markdown

## Contact

- Firstname Lastname, <firstname@example.org>,
  GitHub: [@exampleuser](https://github.com/exampleuser)

More than one maintainer is better than one. An organisation or team account is fine, and is more durable than an individual.

How to fix ​

Add the block above. If you are taking over an existing identifier, update the contact rather than appending to it, and make sure the outgoing maintainer is visible on the pull request.

How to check ​

Run w3id-check with --rule meta/maintainer-github-username to check this rule on its own; without it the tool runs every rule, as the pull request checks do.

sh
node tools/check/bin/w3id-check.js --rule meta/maintainer-github-username ids/my-project

The check recognises the many shapes this information takes across the repository — GitHub username: name, (GitHub: name), a bare @name, a line starting Username: name, a profile URL, a Markdown link. It is deliberately lenient, and reports only when it can find no plausible username anywhere in the identifier. A structured format may replace it later.

Testing your changes covers installing the tool, and what else is worth checking by hand.

See also ​