foster/forgejo
1
0
Fork 0
mirror of https://codeberg.org/forgejo/forgejo.git synced 2024-11-21 08:31:27 -05:00
Code Issues Wiki Activity

Require clear descriptions both for feature and breaking PRs prior to the merge (#28112)

Browse source 
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.
This commit is contained in:
delvh 2023-11-19 02:53:31 +01:00 committed by GitHub
parent 816e46ee7c
commit 0bf021d7c6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 18 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
CONTRIBUTING.md
View file

@ -203,10 +203,20 @@ Some of the key points:
In the PR title, describe the problem you are fixing, not how you are fixing it. \ In the PR title, describe the problem you are fixing, not how you are fixing it. \
Use the first comment as a summary of your PR. \ Use the first comment as a summary of your PR. \
In the PR summary, you can describe exactly how you are fixing this problem. \ In the PR summary, you can describe exactly how you are fixing this problem.
Keep this summary up-to-date as the PR evolves. \ Keep this summary up-to-date as the PR evolves. \
If your PR changes the UI, you must add **after** screenshots in the PR summary. \ If your PR changes the UI, you must add **after** screenshots in the PR summary. \
If you are not implementing a new feature, you should also post **before** screenshots for comparison. \ If you are not implementing a new feature, you should also post **before** screenshots for comparison.
If you are implementing a new feature, your PR will only be merged if your screenshots are up to date.\
Furthermore, feature PRs will only be merged if their summary contains a clear usage description (understandable for users) and testing description (understandable for reviewers).
You should strive to combine both into a single description.
Another requirement for merging PRs is that the PR is labeled correctly.\
However, this is not your job as a contributor, but the job of the person merging your PR.\
If you think that your PR was labeled incorrectly, or notice that it was merged without labels, please let us know.
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 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
```text ```text
@ -255,13 +265,16 @@ Changing the default value of a setting or replacing the setting with another on
#### How to handle breaking PRs? #### How to handle breaking PRs?
If your PR has a breaking change, you must add a `BREAKING` section to your PR summary, e.g. If your PR has a breaking change, you must add two things to the summary of your PR:
``` 1. A reasoning why this breaking change is necessary
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
```md
## :warning: BREAKING :warning: ## :warning: BREAKING :warning:
``` ```
To explain how this will affect users and how to mitigate these changes. Breaking PRs will not be merged as long as not both of these requirements are met.
### Maintaining open PRs ### Maintaining open PRs