Add an issue template for the Coding Standards project

Thanks for making this issue. It has been on my mind for a while.

I have added headings for the doc updates that I have been using on issues already. And moved the 'supporters' section before 'proposed resolution'. I also changed from using a code block to block quotes so I could see what it would look like.

I am not sure about the supporters section. An issue only needs 2 supporters to move forward, it does not need an open ended list. Shall we just limit that to 2?

The remaining tasks focuses on phpcs but the coding standards also cover languages other than php and other tools. I think that needs to be tweaked but I can't look at that now.

formatting fix

I wrote the below at the same time as quieteone, and the posts overlapped. Pasting and re-posting as-is.

The tasks numbers in the proposed template are not in sync with the steps on the parent issue #3365085: Update the coding standards process on the project page because step 1 over there is 'create an issue' which is kind-of being done when you are using the template. But I think it is worth having the step numbers matching, otherwise it gets messy.

I tried to implement the suggested changes in #8 and #9

Added link to the project page for fuller explanation of the steps.
Modifed step 8 to align with the project instuctions

I think the change in #13 is good. I was also confused aboout the duplicity of the titles.

I have a four more questions / suggestions

(a) The phrase "and exactly what language the documented standards would have" seems obscure (maybe people writing standards all the time would understand what this means). My first thought was "American English, like all our documentation" but obviously that is not what it means :) I don't think you mean software language either. Is it meant to be "how strong is the language" i.e use of 'should' vs 'must'? Or does it just mean what wording will be used? Unless theres a good way to re-phrase this, maybe we can drop that bit of the sentence?

(b) Where we have words or titles that are placeholders, that need to be filled in, could we use the recognised convention of enclosing in {curly braces} ? This would make it clear that it is text to be repaced, not an instuction to do something. For example, with the title 1. Add link to the documentation heading that is to change it is not clear to me whether I should replace that with a link, or whether it is an instruction to put the link somewhere below.

(c) "Repeat this heading for each section that requires a change" I think this refers to the link plus the current text and proposed text. If so then it would be clearer to have this below the proposed text, so that you read it all, then see the instruction to repeat, so it's clear what needs to be repeated.

(d) Right at the top, the first title Problem/Motivation has nothing below it, before we get the next title Benefits. It is unclear if anything should be added between them. Under Problem/Motivation do we need a line somthing like "State what is wrong or missing from the current standards".

I'm happy to update the issue summary with #13 and these suggestions, to see how it all looks, once you've had a chance to respond.

Remove documentation changes header from the IS, per #13.

#14
(a) Is this better? "Provide all proposed changes to the Drupal Coding standards and its sub pages. Include links each section that will be changed.

@jonathan1055, yes, please make the changes you suggest. I need to see the whole thing to fully understand and review.

Thanks @quietone. I have made the changes.

I am also wondering if that the Proposed changes should be second in the sequence, after Problem/motivation? Then you read the Benefits and see the Supporters. Having the Benefits before you read what is being proposed seems a little bit in the wrong order. I have not made that change yet (a) because I'm not totally convinced I just want to ask, and (b) it would obscure the edits I have just made.

Modifed the Remaining tasks to keep the numbering in line with the Coding Standards project page.

@jonathan1055, thanks for making the changes. I am happy to go with the current proposal.

As for changing the order, I am not sure. One reason is that the 'Proposed changes' section can be very long and thus one would have to scroll down to find the Benefits and Supporter. The other is from a teaching perspective, where the most effort is often put into motivating the learners to engage with the content. Here, the 'Benefits' is part of the motivation so should be at the beginning of the process. Then there is the 'Supporters' section. That too can be related to motivation, although indirectly. For example, if one knows any of the individuals supporting the proposal that may effect one's willingness to continue reading. So, I would leave the order as is.

I agree with including "sub pages" as per #16, otherwise, even if the changes are a single concept you currently are steared to add an issue for each subpage it seems.

Thanks @quietone, your reasoning in #19 is excellent. Yes, lets leave the order as is. I was looking at it just from the point of view of one determined individual writing the whole issue summary. But of course it may be started by someone then modified by many others, and new people join later. Much better to keep the order as it is now.

@bbrala from #20 I think we have what you want in the current issue summary. There will be one issue, but if several pages need to be changed then each will have a link, current text and proposed text, in that repeated section.

Great :)

Yea!

I have copy/pasted the approved summary from the Issue Summary to the "custom issue summary template" field for this project. I then made a sample issue so we can see it in use, #3395444: Test custom issue summary template . I think this can be closed now and any tweaks can be made in followups.

Setting to Fixed.

Excellent.