Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
167 lines (110 loc) · 5.6 KB

CONTRIBUTING.md

File metadata and controls

167 lines (110 loc) · 5.6 KB

Contributing to the Ultimate Drupal Reference

Thanks for taking the time to contribute.

This repository is intentionally curated. The goal is not to collect as many Drupal links as possible. The goal is to keep a high-signal, modern, maintainable reference for developers and site builders who want good starting points without wading through outdated recommendations.

If you want to help with that, you are very welcome here.

What kinds of contributions are helpful

Good contributions include:

  • fixing outdated or broken links
  • removing resources that are no longer relevant
  • replacing weaker resources with better current ones
  • adding a missing modern Drupal resource that clearly improves the guide
  • improving categorization, wording, or internal linking
  • tightening explanations so readers understand why something belongs here

A very valuable contribution is not only adding something new, but also improving the quality of what is already listed.

Before you open a pull request

Please quickly check the following:

  • Is the resource still relevant for modern Drupal projects?
  • Is it still maintained or still clearly useful?
  • Is there already an official Drupal.org page that covers the same topic better?
  • Does this addition improve the README, or just make it longer?
  • Would you still recommend this to a newcomer today?

If the answer is mostly “no”, it probably should not be added.

What belongs in this repository

This project can include, among other things:

  • official Drupal documentation
  • contributed modules, themes, and distributions
  • high-quality articles and tutorials
  • video resources and talks
  • troubleshooting references
  • community resources that help people learn or get unstuck

What usually does not belong here

To keep the reference useful, please avoid adding:

  • outdated Drupal-version-specific resources that are no longer a good default
  • abandoned or effectively dead projects
  • low-quality SEO articles with little technical depth
  • duplicate links that cover the same thing without adding real value
  • giant lists of alternatives without context
  • resources included only for historical interest

Contribution principles

Please keep these principles in mind:

1. Prefer quality over quantity

This project is intentionally selective. A smaller list with better judgment is more useful than a huge list with weak signal.

2. Prefer current recommendations over historical completeness

Something should not remain in the README just because it used to matter. If it is outdated or no longer a sensible recommendation, it is a candidate for removal.

3. Prefer official documentation first

If an official Drupal.org page covers a topic well, prefer that as the primary reference. Community articles are welcome when they add practical depth, clarity, or a genuinely useful perspective.

4. Keep the wording practical

This is a working reference, not marketing copy. Try to write in a way that helps someone make a better decision faster.

5. Keep the dynamic sections maintainable

For sections like articles and community reads:

  • keep the list short
  • prefer evergreen content
  • remove dead or version-confusing resources
  • replace weaker links instead of endlessly growing the section

Style guidelines

When editing the README:

  • keep the tone professional, personal, and direct
  • write for developers and site builders first
  • avoid unnecessary Drupal-version wording unless it is part of a project name or article title
  • prefer concise explanations over long descriptions
  • preserve the curated nature of the list

For list items:

  • add a short explanation when it helps readers understand why the resource is worth their time
  • avoid copy that sounds vague, inflated, or generic
  • keep category placement sensible and predictable

Commit messages

Please use Conventional Commits for commit messages where practical.

Examples:

  • docs: update README intro
  • docs: refresh troubleshooting section
  • chore: add GitHub issue templates
  • fix: replace broken Drupal.org link

For this repository, the most common types will likely be:

  • docs: for README, CONTRIBUTING, and other documentation content
  • fix: for broken links or incorrect references
  • chore: for repository metadata, templates, and small maintenance tasks

Sorting and consistency

Where items are presented as lists of resources, keep them tidy and consistent.

In general:

  • keep naming accurate
  • use the project’s actual public name
  • keep formatting consistent with surrounding items
  • avoid adding near-duplicate entries in multiple places unless there is a strong reason

Issues vs. pull requests

Open an issue if:

  • you want to suggest a bigger restructuring
  • you are unsure whether a resource belongs here
  • you found outdated guidance or a broken section
  • you want to propose a new category or a change in scope

Open a pull request if:

  • you already know the change is straightforward
  • you are fixing links, wording, categorization, or formatting
  • you are replacing or adding a resource that clearly fits the project

Pull request checklist

Before submitting, please make sure your pull request:

  • keeps the README aligned with the repository’s current scope
  • improves signal rather than adding noise
  • avoids outdated recommendations
  • uses working links
  • reads naturally alongside the existing sections

Final note

The best contributions to this repository usually do one of two things:

  • make the guide more current
  • make the guide more useful

If your change does one of those well, it is probably moving in the right direction.