Problem/Motivation

In #3365085: Update the coding standards process on the project page the following text was agreed to but because it is only about PHP and not about the process steps, I have moved the discussion here.

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. Coding Standards project

Some sections only have the heading.

Current text

The Coding Standards committee manages proposed changes to the Drupal Coding Standards. The members of the committee are listed on the Technical Working group charter.

Join #coding-standards in Drupal Slack to meet and work with others on improving the Drupal coding standards.

Meetings are held every two weeks in #coding-standards on Drupal Slack The minutes of those meetings are transcribed to issues in this project. Ask in #coding-standards when the next meeting will be held.

The Process for Changing Coding Standards

Coding Standards committee members

Proposed text

The Drupal Coding Standards

Drupal coding standards can be found in the Coding standards guide. Changes to the guide should only be made with approval from the Coding Standards committee.

PHP

PHP standards are enforced using PHP_CodeSniffer. The rules used are from that project as well as the Drupal coder project and Slevomat.

CSS

JavaScript

Twig

Spelling

YAML config files

Composer package

The Process for Changing Coding Standards

...

The Coding Standards Committee

The Coding Standards committee manages proposed changes to the Drupal Coding Standards.

Place of business

Join #coding-standards in Drupal Slack to meet and work with others on improving the Drupal coding standards.

Meetings

Meetings are held every two weeks in #coding-standards on Drupal Slack. The minutes of those meetings are transcribed to issues in this project. Ask in #coding-standards when the next meeting will be held.

Coding Standards committee members

...

Comments

quietone created an issue. See original summary.

quietone’s picture

quietone commented
Issue summary: View changes
Related issues: +#3365085: Update the coding standards process on the project page

I've added a suggestion. I am not sure about adding the details of how something is implemented though. We would then have to add that for all the automated tools used.

What else should be on the project page?

catch’s picture

catch
he/him
Primary language English
commented
Related issues: +#3387286: Clarify how front-end coding standards get updated
quietone’s picture

quietone commented
Issue summary: View changes
quietone’s picture

quietone commented
Status: Active » Needs review

I tried to make a version where additional information for the different standards can be added. I also reordered to place what I thought most visitors want to see at the top.

jonathan1055’s picture

jonathan1055 commented
Issue summary: View changes
Status: Needs review » Needs work

This looks good.

I have converted the title to links for CSS, JavaScript, Twig and Spelling, and added new titles for Yaml and Composer package.
The other top-level sections on the main coding standards front page do not have content yet, so not linked from here (yet).

Also I noticed that we have used a link to /docs/develop/standards in the first paragraph and /coding-standards in the paragraph about the committee. This second link gets redirected to /docs/develop/standards. Would it be better to use the same url in both places? Or maybe we don't need the second link? I've seen good practice on many sites where you only link to a page once, otherwise it appears that there is something else to read when infact you have already seen that page.

Likewise, do we need two links to Drupal Slack? One is enough, maybe.

quietone’s picture

quietone commented
Issue summary: View changes

I've removed the second, duplicate links as suggested.

Let's get this piece done and then have a followup to add further details.

quietone’s picture

quietone commented
Status: Needs work » Needs review
jonathan1055’s picture

jonathan1055 commented
Status: Needs review » Reviewed & tested by the community

Thanks for making those changes, it is better for a page not to have repeated active links to the same url.
Looks good to me. RTBC

dww’s picture

dww
we/he/they
commented
Issue summary: View changes
Status: Reviewed & tested by the community » Needs review

Thanks for this, looks like a good improvement!

  1. It's slightly unclear from this summary, but we're not touching the "The Process for Changing Coding Standards" section, right? That's staying where it is? I added it back to the summary for now as I imagine it.
  2. Meanwhile, we were slightly inconsistent with capitalization. Do we want "Coding Standards committee" everywhere? That's what I just changed it to. Hope that's a "friendly amendment". 😅
  3. Also, why were we defining a title attribute in any of these links? It's duplicating the actual link text, which is the most accessible place to put the information (for everyone).
  4. Why do we have "The members of the committee are listed on the Technical Working group charter" if we have <h4>Coding Standards committee members</h4> and a list of members directly on this page? Can we remove that sentence entirely now?
dww’s picture

dww
we/he/they
commented
  1. Re: 10.1: Is the process for changing more relevant as you read this project page than the section on the details of the committee? Should the h3 order be this?
    <h3>The Drupal Coding Standards</h3>
<h3>The Process for Changing Coding Standards</h3>
<h3>The Coding Standards committee</h3>
  2. Re: 10.2: Speaking of inconsistent capitalization, should the last h3 use "Committee"? 😂 How's that for some hyper micro nitpicking? 😬

Thanks, 😊
-Derek

jonathan1055’s picture

jonathan1055 commented

#10.1 Correct, there is no intention to alter the text in 'the process for changing coding standards'

#10.4 The members listed on charters/technical-working-group-charter.md#membership are different to the names shown on the project page. If they are supposed to be the same, then we only want one list.

#11.1 Yes I would say the level of importance should be as you suggest 1. The Standards, 2. The Process, 3. The People

quietone’s picture

quietone commented
Status: Needs review » Reviewed & tested by the community

@dww, thanks for making those improvements. I agree with them so setting to RTBC.

dww’s picture

dww
we/he/they
commented
Issue summary: View changes

Updated summary again to incorporate all my proposals:

  • #10.1: Confirmed
  • #10.4: Remove the sentence and link to TWG charter
  • #11.1: Move / re-order
  • #11.2: Use 'Committee' (capital C) in h3
dww’s picture

dww
we/he/they
commented
Status: Reviewed & tested by the community » Fixed

https://www.drupal.org/node/2465321/revisions/view/13315685/13405201

jonathan1055’s picture

jonathan1055 commented

Just a small point, the first mention of Slack in the 'place of business' paragraph is quite correctly a url to join Slack.

But in the next paragraph 'meetings' could the #coding-standards text be converted to a link to thew actual channel
https://app.slack.com/client/T06GX3JTS/C02LJCF78E8 is the url I have on web browser, but I don't know if this is the same on app / phone. I presume it is?

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.