Problem/Motivation

Our coding standards are out of sync with the standard way technical docs are written, which is to conform to RFC 2119: http://www.ietf.org/rfc/rfc2119.txt

We SHOULD revise our language to conform to that terminology, for consistency and clarity.

Split off from: #1791872-49: [Policy, no patch] Add special tag to identify issues ready for a high level only review

Benefits

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

Three supporters required

  1. https://www.drupal.org/u/{userid} (date that user added support)
  2. https://www.drupal.org/u/{userid} (date that user added support)
  3. https://www.drupal.org/u/{userid} (date that user added support)

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. {link to the documentation heading that is to change}

Current text

Add current text in blockquotes

Proposed text

Add proposed text in blockquotes

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

Remaining tasks

  1. Create this issue in the Coding Standards queue, using the defined template
  2. Add 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 full explanation of these steps see the Coding Standards project page

Comments

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Issue tags: +Coding standards

tagging

Crell’s picture

Crell commented
Title: Revise coding standards to use explicit RFC language » Revise coding standards to use IETF RFC 2119 standards

Updating title, will update the summary momentarily.

http://www.ietf.org/rfc/rfc2119.txt

Crell’s picture

Crell commented

For the record, I am +1.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

For the record, I am +1.

cweagans’s picture

cweagans
He/Him
Primary language English
Location Boise, ID, USA
commented

For the record, I am +1.

tim.plunkett’s picture

tim.plunkett
he/him
Primary language English
Location Philadelphia
commented

I MUST state that, for the record, I am +1

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I'm watching for the wave of people volunteering to take on the task of making the coding standards pages revisions to comply with this... still watching... or at least volunteering to edit one coding standards page?

sun’s picture

sun
Primary language German
Location Karlsruhe
commented

For the disco, I am +1.

I am volunteering to edit the master page about documentation and commenting standards (1354), since I wanted to heavily shorten the text on it anyway (retaining the information, of course), so that's a good opportunity.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I am very scared about node/1354 editing... especially when you say you want to "heavily shorten" the text on it (which seems out of scope for this issue). The documentation on node/1354 is currently working very well for pointing new contributors to finding the complete information, and having it be a bit verbose is useful to me in my efforts to point people to the standards who are not familiar with them. I'd really hate to lose any of the information that is there.

It would be much preferable to limit the scope of edits to what is mentioned in this issue: namely, using should/may/etc. as specific words in standards rather than the sloppy/conversational way we've been writing our standards.

I don't want to start a "revert the revision because it was too drastic" war... please?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Issue summary: View changes

Update summary to reference RFC directly.

alexborsody’s picture

alexborsody commented
Issue summary: View changes

+1 I think this is important. Willing to edit a few pages to use should/may according to these standards. My question is where is the best place to start? Suggestions?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Project: Drupal core » Drupal Technical Working Group
Version: 8.0.x-dev »
Component: documentation » Documentation

Coding standards changes are now part of the TWG

tizzo’s picture

tizzo commented
Project: Drupal Technical Working Group » Coding Standards

Moving this issue to the Coding Standards queue per the new workflow defined in #2428153: Create and document a process for updating coding standards.

Any update on this issue?

quietone’s picture

quietone commented
Issue summary: View changes

This comment from @pfrenssen, provides background that the Drupal standards are deliberately written in a friendly style and avoids using the all caps.

Since I was here I converted to the new project issue template.

quietone’s picture

quietone commented

I have been thinking more about this and based on #13 I think this is a won't fix.

quietone’s picture

quietone commented

This was discussed at a coding standards meeting, discussion '%'. #3414201: Coding Standards Meeting Tuesday 30 January 2024 21:00 UTC. Three committee members replied that they support won't fix.

dww’s picture

dww
we/he/they
commented
Status: Active » Closed (won't fix)

Yeah, 3 core committers all opposed this (@quietone, @catch, @larowlan). I'm also now on the CS committee and do NOT think we SHOULD change our standards to begin SHOUTING, even though EVERYONE else does it. 😅

The CS process has changed a lot over the years since this issue was opened. If anyone strongly wants to revisit this, please open a new issue about it and try to get new supporters, but given how many of the current committers and committee members oppose it, I doubt it's going to happen.

Thanks,
-Derek