Contrib.social

Conflict between coding standards and module documentation guidelines on file naming

Open on Drupal.org →
Created on 11 November 2018, almost 6 years ago
Updated 26 October 2023, 11 months ago

Problem/Motivation

Please modify the Drupal coding standards to bring them in line with the rest of the Drupal ecosystem, and reflect the encouragement of the use of markdown documentation files for Drupal projects.

Suggested new text for the coding standards:

Benefits

If we adopted this change, the Drupal Project would benefit by ...

Three supporters required

  1. {link to user}
  2. {link to user}
  3. {link to user}

Proposed changes

Provide all proposed changes to the Drupal Coding standards → . Give a link to each section that will be changed, and show the current text and proposed text as in the following layout:

1. Drupal coding standards →

All documentation files should have the file name extension ".txt" to make viewing them on Windows systems easier. Also, the file names for such files should be all-caps (e.g. README.txt instead of readme.txt) while the extension itself is all-lowercase (i.e. txt instead of TXT).

Examples: README.txt, INSTALL.txt, TODO.txt, CHANGELOG.txt etc.

The Module documentation guidelines → , however, say:

All contributed modules should provide a README.txt or README.md file in the package. This plain-text file should contain a basic overview of what the module does and how someone may use it.

Documentation files should either be in plain text with the file name extension ".txt", or be valid Markdown syntax with the file name extension ".md".

The base file names should be all-caps ("README" not "readme") but the extension itself should be all-lowercase (".txt" or ".md" not ".TXT" or ".MD").

Examples: README.md, README.txt, INSTALL.md, TODO.txt, CHANGELOG.txt, etc.

2. Repeat the above for each page or sub-page that needs to be changed.

Remaining tasks

  2. List three supporters
  3. Create a Change Record
  4. Review by the Coding Standards Committee
  5. Coding Standards Committee takes action as required
  6. Tagged with 'Needs documentation edits' if Core is not affected
  7. Discussed by the Core Committer Committee, if it impacts Drupal Core
  8. Documentation updates
    1. Edit all pages
    2. Publish change record
    3. Remove 'Needs documentation edits' tag
  9. If applicable, create follow-up issues for PHPCS rules/sniffs changes

For a fuller explanation of these steps see the Coding Standards project page →

🐛 Bug report
Status

Needs work

Component

Coding Standards

Created by

🇺🇸United States bkline@rksystems.com Virginia

Live updates comments and jobs are added and updated live.
  • Documentation

    Primarily changes documentation, not code. For Drupal core issues, select the Documentation component instead of using this tag. In general, component selection is preferred over tag selection.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • Comment 11 months ago →
    🇬🇧United Kingdom jonathan1055

    I have updated the issue summary with the improvements from comments #8 and #10.

    The next thing to do will be to use the new Coding Standards issue template being trialed on #3387167: Add an issue template for the Coding Standards project → . This contains the new process for getting standards agreed and documentation pages updated.

  • Comment 11 months ago →
    🇳🇿New Zealand quietone New Zealand

    @jonathan1055, thanks for updating the IS.

    I haven't found 'all-caps' in a dictionary so am suggesting a change. Also, I don't think the extension includes the '.' nor do I think the examples need to be given twice. So, how about this

    Documentation files should either be in plain text with the file name extension "txt", or be valid Markdown syntax with the file name extension "md".

    The base file name should be all upper case and the extension itself should be all-lowercase.

    Examples: README.md, README.txt, INSTALL.md, TODO.txt, CHANGELOG.txt.

  • Status changed to Needs work 11 months ago
  • Comment 11 months ago →
    🇦🇺Australia alex.skrypnyk Melbourne

    I have to agree with #13 and disagree with #14, sorry. I do not see a point to linking to Wikipedia and then, later, re-linking to D.O - this feels like following a process for the sake of the process. Majority of developers already know what Markdown is. If we want it to be formatted in a specific way according to Drupal standards, then we have a page for it in D.O. Although that page does not have much right now, it will be filled separately outside of this issue, which is not about the Markdown format but about the file naming conventions.

    I'm putting this issue back to Needs work to discuss this more.

  • Assigned to Mohd Sahzad
  • Comment 11 months ago →
    🇮🇳India Mohd Sahzad
  • Issue was unassigned.
  • Comment 11 months ago →
    🇮🇳India Mohd Sahzad
  • Comment 11 months ago →
    🇳🇿New Zealand quietone New Zealand

    Updated to use the new coding standards issue template.

    Are there changes to be made to "The Module documentation guidelines"?

  • Comment 11 months ago →
    🇺🇸United States bkline@rksystems.com Virginia

    #23 None of which I'm aware. What did you have in mind? This issue assumes that the implication in the module documentation guidelines (that the use of markdown for such documentation is appropriate) is correct.

    I had no idea when I pointed out the discrepancy five years ago that it would turn out to be so controversial. 😉

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024