Guidelines for module categories updates

These guidelines have been created to moderate the process of changes to module project categories to ensure usability, search, and a consistent experience for the community. As the categories are used by more people across projects, people will have opinions and changes need to be moderated. This includes suggestions for new categories, edits for existing ones, and possibly deprecation of existing categories. However, a category cannot be simply added to the category listing, since there may be conflicting categories elsewhere in the taxonomy, or the meaning of the category may be unclear or defined differently between stakeholders. 

Process steps

The following are detailed explanations of the steps for the module project category change process. 

Step 1: Create issue

The initial step for a submitter nominating a new category or a change to an existing category is to file an issue using Drupal’s issue queue so the process can be as transparent as possible.

Before proceeding with creating issues regarding changes to module project categories, review the current Module categories documentation guide, and search for any possible duplicate or related issues.

Create the issue in the Drupal.org content issue queue.

The issue title should start with Module Category Change: [add requested change] (for example, Module Category Change: Rename Decoupled to Headless) and should be tagged with the issue tag module category change so they can be easily identified and followed by interested members of the community.

The content of the issue should include as much detail as needed for the people involved to make an informed decision.

At a minimum, the request should provide:

• The type of change (New category/Edit category/Delete category)
• The category name (both new and old for name-change requests)
• The category description (may be excluded for requests that do not change it)
• Example modules that would be affected by the requested change 
• The justification for the request and the expected improvement (for example, data, trends, documented misunderstandings)
• An explanation of how adding or changing the category will affect stakeholders
• A migration plan, if one is needed

Volunteers and contributors participating in each issue will then move through the steps below to closure.

Step 2: Open review

Inform possible stakeholders upon the creation of the issue to open the review process. Users with a vested interest in the change request (maintainers, contributors, participants, etc.) should voice their opinions on the issue to improve any proposed resolution.

The issue should not be implemented for at least 30 days, to give the community ample opportunity to provide input. Users are encouraged to “+1” or “upvote” the idea presented in an issue, rather than open duplicates.

The community should use its expertise to evaluate each category to determine if it’s the right category to use, any alternative categories that could be used (synonyms or related categories), and if possible, propose the category. Comments on the issue should guide what the impact of the change will have not only on the system but also on stakeholders.

Step 3: Acceptance

Decision-making criteria

• What impact will the proposed change have on existing users and the system?
• How many module projects would utilize this category change right away? (Could 100 modules be tagged with this category today? 1000?)
• How many community upvotes have there been for this change?
• Does this change reflect a contrib ecosystem (for example, Drush, Webform, or Drupal Commerce)?
• Is this change represented by an existing category whose scope could be expanded or the description altered instead?

Additional considerations for terms

• Compound categories are not allowed (for example, using slashes or ampersands unless part of a very defined term in the technology sector, like Import/Export).
• Parentheticals should not be used to add context.
• Acronyms should always be spelled out (but may use parentheses for the acronym, as in Search Engine Optimization (SEO)).
• Terms and descriptions should use American English (en-US locale) for spelling and must be spelled correctly. Descriptions should be grammatically correct.

After an appropriate period of open public comment, and once consensus has been reached, the issue can be marked Reviewed & Tested by the Community, and move on to implementation.

In the event consensus is not reached (that is, after 60 days the issue has NOT addressed each point from Step 2 above), it should be marked Postponed (Maintainer needs more info).

In the event the request is denied, the status will be changed to Closed (Won't fix), and no further action will be taken.

Step 4: Implementation

Once a decision has been made, recorded, and reported, and the issue has been set to Reviewed & Tested by the Community, the Drupal.org site moderators and administrators should address the issue and should make public a date for when the change will be implemented. When the taxonomy change has been implemented, it should be marked Fixed.

Step 5: Stakeholder update

Once the category change is approved, or rejected, the user who submitted the request (as well as anyone following the issue in the queue) will be automatically notified of the decision (as long as they are subscribed to the issue). Additionally, the #maintainers channel in Drupal Slack should be notified by the Drupal.org site moderators about impactful changes.