Skip to content

Commit 0bf021d

Browse files
authored
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.
1 parent 816e46e commit 0bf021d

File tree

1 file changed

+18
-5
lines changed

1 file changed

+18
-5
lines changed

CONTRIBUTING.md

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -203,10 +203,20 @@ Some of the key points:
203203

204204
In the PR title, describe the problem you are fixing, not how you are fixing it. \
205205
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+
207208
Keep this summary up-to-date as the PR evolves. \
208209
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+
210220
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
211221

212222
```text
@@ -255,13 +265,16 @@ Changing the default value of a setting or replacing the setting with another on
255265

256266
#### How to handle breaking PRs?
257267

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:
259269

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
261274
## :warning: BREAKING :warning:
262275
```
263276

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.
265278

266279
### Maintaining open PRs
267280

0 commit comments

Comments
 (0)