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
Require clear descriptions both for feature and breaking PRs prior to the merge (#28112)
When writing the release blog, it is really annoying and time-consuming
to re-discover and write down how a feature behaves and capture a
screenshot of it, for every single feature merged since the last
release.
This should not be the responsibility of maintainers, but rather of the
person implementing a feature in the first place.
They know best how to use the feature and how to gather screenshots for
it.
Similarly for breaking changes and their effects.
As such, let's require everything to be up-to-date and easily
understandable before merging features or breaking changes.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+18-5Lines changed: 18 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -203,10 +203,20 @@ Some of the key points:
203
203
204
204
In the PR title, describe the problem you are fixing, not how you are fixing it. \
205
205
Use the first comment as a summary of your PR. \
206
-
In the PR summary, you can describe exactly how you are fixing this problem. \
206
+
In the PR summary, you can describe exactly how you are fixing this problem.
207
+
207
208
Keep this summary up-to-date as the PR evolves. \
208
209
If your PR changes the UI, you must add **after** screenshots in the PR summary. \
209
-
If you are not implementing a new feature, you should also post **before** screenshots for comparison. \
210
+
If you are not implementing a new feature, you should also post **before** screenshots for comparison.
211
+
212
+
If you are implementing a new feature, your PR will only be merged if your screenshots are up to date.\
213
+
Furthermore, feature PRs will only be merged if their summary contains a clear usage description (understandable for users) and testing description (understandable for reviewers).
214
+
You should strive to combine both into a single description.
215
+
216
+
Another requirement for merging PRs is that the PR is labeled correctly.\
217
+
However, this is not your job as a contributor, but the job of the person merging your PR.\
218
+
If you think that your PR was labeled incorrectly, or notice that it was merged without labels, please let us know.
219
+
210
220
If your PR closes some issues, you must note that in a way that both GitHub and Gitea understand, i.e. by appending a paragraph like
211
221
212
222
```text
@@ -255,13 +265,16 @@ Changing the default value of a setting or replacing the setting with another on
255
265
256
266
#### How to handle breaking PRs?
257
267
258
-
If your PR has a breaking change, you must add a `BREAKING` section to your PR summary, e.g.
268
+
If your PR has a breaking change, you must add two things to the summary of your PR:
259
269
260
-
```
270
+
1. A reasoning why this breaking change is necessary
271
+
2. A `BREAKING` section explaining in simple terms (understandable for a typical user) how this PR affects users and how to mitigate these changes. This section can look for example like
272
+
273
+
```md
261
274
## :warning: BREAKING :warning:
262
275
```
263
276
264
-
To explain how this will affect users and how to mitigate these changes.
277
+
Breaking PRs will not be merged as long as not both of these requirements are met.
0 commit comments