You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat: update contribution workflow based on guideline generated as comment (#251)
* feat: update contribution workflow based on guideline generated as content
* fix: make step 5 shorter to fit inside
* fix: remove extraneous line breaks
* fix: make the written text match the flowchart
* fix: further clarify steps
* fix: typo
* fix: note that generated guideline content regenerates if body updated
* Clarifying timing
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: update section heading to sound better
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: update the table of contents entry to fit section header
* fix: update voicing to be consistent
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: update casing consistency
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: update casing consistency
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: tense
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: clarify how to find .rst file in which to place guideline
* fix: resolve odd formatting
* Clarify wording
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* Clarify wording
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* Deleting unneeded bit
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* Removing bit not needed anymore
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: try GitHub's syntax for notes
* chore: update to fit new fashion of adding individual guideline source files
* docs: note that you need to include the newly added file to chapter index.rst
* fix: links in table of contents
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: links in table of contents
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: clarify wording of how issues should become PRs
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: clean up run-on sentence
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: clarify which sections of comment to reference
* fix: clarify flow for duplicative rules
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
* fix: simplify by breaking into two sentences
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
---------
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>
PR --> S8{{"8: Subcommittee member <br> approves & queues;<br>merges to main"}} --> Main[[main]]
55
+
Main --> End(["9: End"])
51
56
```
52
57
53
58
### Note on Chapter Layout
@@ -75,29 +80,88 @@ Note that the FLS ID should be filled according to the FLS paragraph ID for whic
75
80
76
81
You would then pull `fls_4rhjpdu4zfqj` to place in the FLS ID field.
77
82
78
-
### 2) Create a Draft with a Member
79
83
80
-
A member of the Coding Guidelines Subcommittee should get you a first review with some feedback within 14 days of submission. You'll work with one or more members to flesh out the concept and ensure the guideline is well prepared.
84
+
### 2) Guideline Generated as a Comment
85
+
86
+
A GitHub Action will fire, adding a comment to your newly created issue with
87
+
the contents of the coding guideline prepared written out correctly
88
+
in reStructuredText.
89
+
90
+
Note that if you later update the body of the coding guideline issue this will
91
+
fire the GitHub Action again and update the original comment with the new
92
+
contents converted to reStructuredText.
93
+
94
+
### 3) Create a Draft with a Member
95
+
96
+
Within 14 days of your submission, a member of the Coding Guidelines Subcommittee should give you a first review. You'll work with them (and other members) to flesh out the concept and ensure the guideline is well prepared for a Pull Request.
97
+
98
+
### 4) Create the PR
99
+
100
+
> [!NOTE]
101
+
> Here's a list of recommended prerequisites that shall be fulfilled before turning an issue into a PR:
102
+
>
103
+
> * The new rule isn't already covered by another rule
104
+
> * OR, in case there is(are) already another rule(s),
105
+
> * The existing rule(s) need(s) to be linked to the new rule,
106
+
> * AND the new rule needs to link to the existing rule(s).
107
+
> * All sections contain some content
108
+
> * Content written may be *incomplete*, but must not be *incorrect*
109
+
> *`🧪 Code Example Test Results` section shows all example code compiles
110
+
111
+
As soon as these prerequisites are fulfilled, the draft shall be marked as PR-ready by a subcommittee member, by labeling the issue with `sign-off: create pr`. This denotes that you should create a Pull Request with your Guideline. Further discussion about the amount and correctness of its content shall then be done on the Pull Request itself.
112
+
113
+
The contents of the PR should be based on the bot comment containing the generated RST form of your guideline, as seen in [Step 2](#2-guideline-generated-as-a-comment). The comment has the exact file content you'll need.
114
+
115
+
In order to ensure your guideline appears when rendering the document, reference the generated comment from [Step 2](#2-guideline-generated-as-a-comment). All the steps necessary should appear below the headings `📁 Target Location` and `🗂️ Update Chapter Index`.
81
116
82
-
### 3) A Pull Request is generated
117
+
Make sure to include this command in the body of your PR, where `xyz`is the number of the issue you opened in [Step 1](#1-submit-coding-guideline-issue):
83
118
84
-
Once an issue has been well-developed enough, a subcommittee member will mark the issue with the label `sign-off: create pr from issue` to generate a pull request. You will see a GitHub Workflow trigger and a pull request will be automatically created.
119
+
> `closes #xyz`
85
120
86
-
### 4) Iterate on Feedback
121
+
This will ensure issue `#xyz` is closed when your Pull Request gets merged.
122
+
123
+
124
+
### 5) Iterate on Feedback
125
+
126
+
#### 5.1) Member Begins Review
87
127
88
128
The generated Pull Request may attract additional feedback or simply be an easier place to suggest targeted edits.
89
129
90
130
As the contributor of the coding guideline and opener of the issue, you'll respond to comments, discuss, all the normal things on the pull request.
91
131
92
-
#### 4.1) Apply changes to the Guideline's Issue
132
+
#### 5.2) Update the PR Based on Feedback
133
+
134
+
If you agree with the suggested changes, you've got two options:
135
+
136
+
- Iterate directly on the Pull Request, if you're comfortable with reStructuredText to do so
137
+
- If you'd rather make revisions in Markdown, you can return to the issue
138
+
from [1) Submit coding guideline issue](#1-submit-coding-guideline-issue)
139
+
to regenerate the reStructured Text guideline form by following steps
140
+
outlined in
141
+
[6) Contributor Applies Feedback on Issue](#6-contributor-applies-feedback-on-issue)
142
+
and
143
+
[7) Contributor Applies Regenerated Guideline to PR](#7-contributor-applies-regenerated-guideline-to-pr)
93
144
94
-
If you agree with the suggested changes, then rather than making changes on the opened pull request, you will return to the original issue you opened via the coding guideline issue template, and make the updates there.
145
+
### 6) Contributor Applies Feedback on Issue
95
146
96
-
#### 4.2) Re-generate the Pull Request
147
+
(Optional, if not comfortable with reStructured Text from
148
+
[5.2) Update the PR Based on Feedback](#52-update-the-pr-based-on-feedback))
97
149
98
-
When you have completed all feedback given to you, ping one of the subcommittee members. They will then remove and affix the label `sign-off: create pr from issue` to push the changes made in the issue to the already opened pull request.
150
+
The contributor edits the body of the issue summary, reflecting suggestions and then saves it.
151
+
You will then momentarily see a new comment added to the issue containing the updated
152
+
guideline content written in reStructured Text.
99
153
100
-
### 5) Your Guideline gets merged
154
+
### 7) Contributor Applies Regenerated Guideline to PR
155
+
156
+
(Optional, if not comfortable with reStructured Text from
157
+
[5.2) Update the PR Based on Feedback](#52-update-the-pr-based-on-feedback))
158
+
159
+
The contributor then copy + pastes the contents of the guideline from
160
+
[6) Contributor Applies Feedback on Issue](#6-contributor-applies-feedback-on-issue)
161
+
and overwrites the contents of their feature branch, so that the feedback is
162
+
reflected into the Pull Request.
163
+
164
+
### 8) Your Guideline gets merged
101
165
102
166
Once the coding guideline contents have passed review, a subcommittee member will approve the pull request, and put it on the merge queue to be merged.
103
167
@@ -108,9 +172,7 @@ That's it!
108
172
109
173
## Writing a guideline locally (less typical, not recommended)
110
174
111
-
While it is possible to create guidelines locally and open pull requests yourself, we encourage contributors to make use of the process described above since it handled some of the fiddly details for you as a guideline writer.
112
-
113
-
Generally speaking, pull requests for guidelines which do not follow the issue to pull request workflow described above will be closed with a recommendation to follow the workflow.
175
+
While it is possible to create guidelines locally, we encourage contributors to make use of the process described above since it handles some of the fiddly details for you as a guideline writer.
0 commit comments