Add a few more comments to the CONTRIBUTING.md document (#18469)
* Explain how to title your Backport PR * Advise that the first comment in a PR should explain the PR * Include information about BREAKING changes * Include information about backports/frontports * Add reference command for creating backports * Add reference commandline for creating large characters * Add information about updating docs/config.yaml * Update year in the copyright Signed-off-by: Andrew Thornton <art27@cantab.net>
This commit is contained in:
parent
f9b27d2d46
commit
342c6917e2
1 changed files with 74 additions and 4 deletions
|
@ -134,6 +134,15 @@ Some of the key points:
|
||||||
if that is not related to your PR, please make *another* PR for that.
|
if that is not related to your PR, please make *another* PR for that.
|
||||||
* Split big pull requests into multiple small ones. An incremental change
|
* Split big pull requests into multiple small ones. An incremental change
|
||||||
will be faster to review than a huge PR.
|
will be faster to review than a huge PR.
|
||||||
|
* Use the first comment as a summary explainer of your PR and you should keep this up-to-date as the PR evolves.
|
||||||
|
|
||||||
|
If your PR could cause a breaking change you must add a BREAKING section to this comment e.g.:
|
||||||
|
|
||||||
|
```
|
||||||
|
## :warning: BREAKING :warning:
|
||||||
|
```
|
||||||
|
|
||||||
|
To explain how this could affect users and how to mitigate these changes.
|
||||||
|
|
||||||
## Styleguide
|
## Styleguide
|
||||||
|
|
||||||
|
@ -203,13 +212,74 @@ In general, HTTP methods are chosen as follows:
|
||||||
* **PUT** endpoints return status **No Content (204)**, used to **add/assign** existing Objects (e.g. User) to something (e.g. Org-Team)
|
* **PUT** endpoints return status **No Content (204)**, used to **add/assign** existing Objects (e.g. User) to something (e.g. Org-Team)
|
||||||
* **PATCH** endpoints return changed object and status **OK (200)**, used to **edit/change** an existing object
|
* **PATCH** endpoints return changed object and status **OK (200)**, used to **edit/change** an existing object
|
||||||
|
|
||||||
|
|
||||||
An endpoint which changes/edits an object expects all fields to be optional (except ones to identify the object, which are required).
|
An endpoint which changes/edits an object expects all fields to be optional (except ones to identify the object, which are required).
|
||||||
|
|
||||||
### Endpoints returning lists should
|
### Endpoints returning lists should
|
||||||
* support pagination (`page` & `limit` options in query)
|
* support pagination (`page` & `limit` options in query)
|
||||||
* set `X-Total-Count` header via **SetTotalCountHeader** ([example](https://github.com/go-gitea/gitea/blob/7aae98cc5d4113f1e9918b7ee7dd09f67c189e3e/routers/api/v1/repo/issue.go#L444))
|
* set `X-Total-Count` header via **SetTotalCountHeader** ([example](https://github.com/go-gitea/gitea/blob/7aae98cc5d4113f1e9918b7ee7dd09f67c189e3e/routers/api/v1/repo/issue.go#L444))
|
||||||
|
|
||||||
|
## Large Character Comments
|
||||||
|
|
||||||
|
Throughout the codebase there are large-text comments for sections of code, e.g.:
|
||||||
|
|
||||||
|
```go
|
||||||
|
// __________ .__
|
||||||
|
// \______ \ _______ _|__| ______ _ __
|
||||||
|
// | _// __ \ \/ / |/ __ \ \/ \/ /
|
||||||
|
// | | \ ___/\ /| \ ___/\ /
|
||||||
|
// |____|_ /\___ >\_/ |__|\___ >\/\_/
|
||||||
|
// \/ \/ \/
|
||||||
|
```
|
||||||
|
|
||||||
|
These were created using the `figlet` tool with the `graffiti` font.
|
||||||
|
|
||||||
|
A simple way of creating these is to use the following:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
figlet -f graffiti Review | sed -e's+^+// +' - | xclip -sel clip -in
|
||||||
|
```
|
||||||
|
|
||||||
|
## Backports and Frontports
|
||||||
|
|
||||||
|
Occasionally backports of PRs are required.
|
||||||
|
|
||||||
|
The backported PR title should be:
|
||||||
|
|
||||||
|
```
|
||||||
|
Title of backported PR (#ORIGINAL_PR_NUMBER)
|
||||||
|
```
|
||||||
|
|
||||||
|
The first two lines of the summary of the backporting PR should be:
|
||||||
|
|
||||||
|
```
|
||||||
|
Backport #ORIGINAL_PR_NUMBER
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
with the rest of the summary matching the original PR. Similarly for frontports
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
The below is a script that may be helpful in creating backports. YMMV.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/sh
|
||||||
|
PR="$1"
|
||||||
|
SHA="$2"
|
||||||
|
VERSION="$3"
|
||||||
|
|
||||||
|
if [ -z "$SHA" ]; then
|
||||||
|
SHA=$(gh api /repos/go-gitea/gitea/pulls/$PR -q '.merge_commit_sha')
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [ -z "$VERSION" ]; then
|
||||||
|
VERSION="v1.16"
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo git checkout origin/release/"$VERSION" -b backport-$PR-$VERSION
|
||||||
|
git checkout origin/release/"$VERSION" -b backport-$PR-$VERSION
|
||||||
|
git cherry-pick $SHA && git commit --amend && git push zeripath backport-$PR-$VERSION && xdg-open https://github.com/go-gitea/gitea/compare/release/"$VERSION"...zeripath:backport-$PR-$VERSION
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
## Developer Certificate of Origin (DCO)
|
## Developer Certificate of Origin (DCO)
|
||||||
|
|
||||||
|
@ -351,7 +421,7 @@ be reviewed by two maintainers and must pass the automatic tests.
|
||||||
* If it is bugfix version create PR for changelog on branch `release/v$vmaj.$vmin` and wait till it is reviewed and merged.
|
* If it is bugfix version create PR for changelog on branch `release/v$vmaj.$vmin` and wait till it is reviewed and merged.
|
||||||
* Add a tag as `git tag -s -F release.notes v$vmaj.$vmin.$`, release.notes file could be a temporary file to only include the changelog this version which you added to `CHANGELOG.md`.
|
* Add a tag as `git tag -s -F release.notes v$vmaj.$vmin.$`, release.notes file could be a temporary file to only include the changelog this version which you added to `CHANGELOG.md`.
|
||||||
* And then push the tag as `git push origin v$vmaj.$vmin.$`. Drone CI will automatically create a release and upload all the compiled binary. (But currently it doesn't add the release notes automatically. Maybe we should fix that.)
|
* And then push the tag as `git push origin v$vmaj.$vmin.$`. Drone CI will automatically create a release and upload all the compiled binary. (But currently it doesn't add the release notes automatically. Maybe we should fix that.)
|
||||||
* If needed send PR for changelog on branch `main`.
|
* If needed send a frontport PR for the changelog to branch `main` and update the version in `docs/config.yaml` to refer to the new version.
|
||||||
* Send PR to [blog repository](https://gitea.com/gitea/blog) announcing the release.
|
* Send PR to [blog repository](https://gitea.com/gitea/blog) announcing the release.
|
||||||
|
|
||||||
## Copyright
|
## Copyright
|
||||||
|
@ -359,7 +429,7 @@ be reviewed by two maintainers and must pass the automatic tests.
|
||||||
Code that you contribute should use the standard copyright header:
|
Code that you contribute should use the standard copyright header:
|
||||||
|
|
||||||
```
|
```
|
||||||
// Copyright 2020 The Gitea Authors. All rights reserved.
|
// Copyright 2022 The Gitea Authors. All rights reserved.
|
||||||
// Use of this source code is governed by a MIT-style
|
// Use of this source code is governed by a MIT-style
|
||||||
// license that can be found in the LICENSE file.
|
// license that can be found in the LICENSE file.
|
||||||
```
|
```
|
||||||
|
|
Reference in a new issue