Guidance for naming and versioning community modules

[abea]

A while back there was community discussion on the Apostrophe Discord server about best practices for naming community-built modules. These would be modules built and maintained by developers outside in the Apostrophe core team, but intended for public use. The core team discussed this topic internally and came up with some best practice recommendations for the community. We're interested to hearing from community devs as we start formalizing best practices like this.

The question

There are a few aspects to the question of how to name community modules. Before that, there are a couple of aspects of naming that we are not concerned with here: the marketing name (for the most part) and the unique npm identifier. "Moment.js" and moment are examples of this (though unrelated to Apostrophe). Apostrophe core team members could have fun debating what makes a good package name for sure. But ultimately it is up to the maintainers to decide how they want other people to find and know their module.

Other parts of naming we are more concerned about are:

1. How the package name reflects its association with Apostrophe.
2. How the package associates itself with a particular version of Apostrophe.

The original question that came up in Discord was from a developer who wanted it to be clear that a module was for Apostrophe 3 (A3) projects, not A2 projects. Some initial suggestions involved the word "apostrophe," which raised that additional question about confusion around a module's status with regards to the core team.

Let's take these one at a time.

Indicating association with Apostrophe

If you want your package name to indicate that it is used with Apostrophe, the recommended practice is to use apos as a prefix. That is regardless of what Apostrophe core version it supports. So an advanced site search module could be apos-super-search. This reflects association with Apostrophe without overlapping with core team naming practices.

More importantly, we strongly discourage developers from using the apostrophe- prefix. The names of Apostrophe 2 modules created and maintained by the core team start that way. Even though other package metadata can indicate who the author is, we would like to keep that as a clear indicator of official A2 modules.

Finally, do you want to name your new module something totally unrelated to Apostrophe, such as seo-crusher? Go for it! There is value in indicating a relationship to Apostrophe, but that certainly isn't necessary. The README and other metadata can also help indicate the same thing.

Indicating a particular major version of Apostrophe

As we researched other open source community plugin-naming practices, we found a few different approaches to connecting a software package with a particular major version. Some use the same major version number for the package as the core CMS software. Many others simply tell developers which versions are supported in README text.

For Apostrophe, the recommended practice is to use the peerDependencies metadata property and the README. In case you are not familiar with it, an npm package.json file can include a peerDependencies property that says what other packages should be used along-side it.

In the case of Apostrophe 3, the property would look something like this:

{
  "name": "@companyname/apos-search",
  "version": "1.0.0",
  "peerDependencies": {
    "apostrophe": "^3.0.0"
  }
}

The peerDependencies property can be more specific if the module requires a particular minimum version, e.g.,^3.10.0. Be sure to start with a caret (^) so that future 3.x versions (in this case) are also accepted.

We don't recommend including the major version in the package name, apos3-search. That prevents you from releasing a new major version of the same package that supports the next major version of Apostrophe. There are not many notable examples of that kind of practice in Node.js package development.

We also don't recommend versioning the package to match the Apostrophe major version. So you should not need to make the first release of your A3 module 3.0.0. For one thing, that is not clear semantic versioning. People may wonder where the other two major versions are. For another thing, being able to bump a major version while working with the same Apostrophe version gives you the freedom to make breaking changes as needed. That is one reason the core Apostrophe team stopped the parallel major version practice even before A3.

In addition to these recommendations, be sure to follow general best practices for semantic versioning.

Namespacing

You may have noticed that A3 modules all start with @apostrophecms/. That is the official Apostrophe namespace and npm "organization." By using this namespace, or "scope," for npm packages, developers can know for sure that the package is created and maintained by the Apostrophe team. As an independent developer, or partner organization, you can do the same thing.

Using an npm scope means that you never have to worry about a package name being already in use. We published @apostrophecms/seo, but you could also publish @superdevs/seo (or @superdevs/apos-seo). You can use either an npm user name or organization as the scope name. Be sure to choose wisely if you create an npm organization for this, since you may want to use that same organization for many future packages.

We recommend using an npm scope to namespace module packages, however it is more a matter of your preference. Your decision on that does not effect the Apostrophe community much, so you are welcome to publish without a scope as well.

We do ask that you do not publish with an Apostrophe-related npm scope. That would simply not be cool. It could be very misleading for other developers. Better to keep npm scopes to your username, company name, or other brand name. So @code-monkeys is great. @apostrophe-world would not be so great.

Final thoughts

These are best practices. If you have ever published a module to npm you know that no one can really stop you from using a name that isn't already in use (other than trademark enforcement). These recommendations are meant to make things clearer for the Apostrophe community and remove one decision off your mind as you work on a new module.

We want to support Apostrophe community developers as they share their work with others. If you have questions or concerns about these recommendations, please let us know.

[myovchev]

Nothing to add. The perfect guideline and is exactly how I'd see it working for everyone.