Update `CONTRIBUTING.md` (#24492) · oppi.li/perf-test@116066e

+382 -261

1 changed file

expand all

+382 -261

CONTRIBUTING.md

··· 1 1 # Contribution Guidelines 2 2 3 - ## Table of Contents 3 + <details><summary>Table of Contents</summary> 4 4 5 5 - [Contribution Guidelines](#contribution-guidelines) 6 - - [Table of Contents](#table-of-contents) 7 6 - [Introduction](#introduction) 8 - - [Bug reports](#bug-reports) 9 - - [Discuss your design](#discuss-your-design) 10 - - [Testing redux](#testing-redux) 11 - - [Vendoring](#vendoring) 7 + - [Issues](#issues) 8 + - [How to report issues](#how-to-report-issues) 9 + - [Types of issues](#types-of-issues) 10 + - [Discuss your design before the implementation](#discuss-your-design-before-the-implementation) 11 + - [Building Gitea](#building-gitea) 12 + - [Dependencies](#dependencies) 13 + - [Backend](#backend) 14 + - [Frontend](#frontend) 15 + - [Design guideline](#design-guideline) 16 + - [Styleguide](#styleguide) 17 + - [Copyright](#copyright) 18 + - [Testing](#testing) 12 19 - [Translation](#translation) 13 - - [Building Gitea](#building-gitea) 14 20 - [Code review](#code-review) 15 - - [Styleguide](#styleguide) 16 - - [Design guideline](#design-guideline) 21 + - [Pull request format](#pull-request-format) 22 + - [PR title and summary](#pr-title-and-summary) 23 + - [Milestone](#milestone) 24 + - [Labels](#labels) 25 + - [Breaking PRs](#breaking-prs) 26 + - [What is a breaking PR?](#what-is-a-breaking-pr) 27 + - [How to handle breaking PRs?](#how-to-handle-breaking-prs) 28 + - [Maintaining open PRs](#maintaining-open-prs) 29 + - [Getting PRs merged](#getting-prs-merged) 30 + - [Final call](#final-call) 31 + - [Commit messages](#commit-messages) 32 + - [PR Co-authors](#pr-co-authors) 33 + - [PRs targeting `main`](#prs-targeting-main) 34 + - [Backport PRs](#backport-prs) 35 + - [Documentation](#documentation) 17 36 - [API v1](#api-v1) 37 + - [GitHub API compatability](#github-api-compatability) 38 + - [Adding/Maintaining API routes](#addingmaintaining-api-routes) 39 + - [When to use what HTTP method](#when-to-use-what-http-method) 40 + - [Requirements for API routes](#requirements-for-api-routes) 41 + - [Backports and Frontports](#backports-and-frontports) 42 + - [What is backported?](#what-is-backported) 43 + - [How to backport?](#how-to-backport) 44 + - [Format of backport PRs](#format-of-backport-prs) 45 + - [Frontports](#frontports) 18 46 - [Developer Certificate of Origin (DCO)](#developer-certificate-of-origin-dco) 19 47 - [Release Cycle](#release-cycle) 20 48 - [Maintainers](#maintainers) 21 - - [Owners](#owners) 49 + - [Technical Oversight Committee (TOC)](#technical-oversight-committee-toc) 50 + - [Current TOC members](#current-toc-members) 51 + - [Previous TOC/owners members](#previous-tocowners-members) 52 + - [Governance Compensation](#governance-compensation) 53 + - [TOC \& Working groups](#toc--working-groups) 54 + - [Roadmap](#roadmap) 22 55 - [Versions](#versions) 23 56 - [Releasing Gitea](#releasing-gitea) 24 - - [Copyright](#copyright) 57 + 58 + </details> 25 59 26 60 ## Introduction 27 61 28 - This document explains how to contribute changes to the Gitea project. 29 - It assumes you have followed the 30 - [installation instructions](https://docs.gitea.io/en-us/). 31 - Sensitive security-related issues should be reported to 32 - [security@gitea.io](mailto:security@gitea.io). 62 + This document explains how to contribute changes to the Gitea project. \ 63 + It assumes you have followed the [installation instructions](https://docs.gitea.io/en-us/). \ 64 + Sensitive security-related issues should be reported to [security@gitea.io](mailto:security@gitea.io). 65 + 66 + For configuring IDEs for Gitea development, see the [contributed IDE configurations](contrib/ide/). 67 + 68 + ## Issues 69 + 70 + ### How to report issues 71 + 72 + Please search the issues on the issue tracker with a variety of related keywords to ensure that your issue has not already been reported. 73 + 74 + If your issue has not been reported yet, [open an issue](https://github.com/go-gitea/gitea/issues/new) 75 + and answer the questions so we can understand and reproduce the problematic behavior. \ 76 + Please write clear and concise instructions so that we can reproduce the behavior — even if it seems obvious. \ 77 + The more detailed and specific you are, the faster we can fix the issue. \ 78 + It is really helpful if you can reproduce your problem on a site running on the latest commits, i.e. <https://try.gitea.io>, as perhaps your problem has already been fixed on a current version. \ 79 + Please follow the guidelines described in [How to Report Bugs Effectively](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html) for your report. 80 + 81 + Please be kind, remember that Gitea comes at no cost to you, and you're getting free help. 82 + 83 + ### Types of issues 84 + 85 + Typically, issues fall in one of the following categories: 86 + 87 + - `bug`: Something in the frontend or backend behaves unexpectedly 88 + - `security issue`: bug that has serious implications such as leaking another users data. Please do not file such issues on the public tracker and send a mail to security@gitea.io instead 89 + - `feature`: Completely new functionality. You should describe this feature in enough detail that anyone who reads the issue can understand how it is supposed to be implemented 90 + - `enhancement`: An existing feature should get an upgrade 91 + - `refactoring`: Parts of the code base don't conform with other parts and should be changed to improve Gitea's maintainability 33 92 34 - For configuring IDE or code editor to develop Gitea see [IDE and code editor configuration](contrib/ide/) 93 + ### Discuss your design before the implementation 35 94 36 - ## Bug reports 95 + We welcome submissions. \ 96 + If you want to change or add something, please let everyone know what you're working on — [file an issue](https://github.com/go-gitea/gitea/issues/new) or comment on an existing one before starting your work! 37 97 38 - Please search the issues on the issue tracker with a variety of keywords 39 - to ensure your bug is not already reported. 98 + Significant changes such as new features must go through the change proposal process before they can be accepted. \ 99 + This is mainly to save yourself the trouble of implementing it, only to find out that your proposed implementation has some potential problems. \ 100 + Furthermore, this process gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits inside 101 + the goals for the project and tools. 40 102 41 - If unique, [open an issue](https://github.com/go-gitea/gitea/issues/new) 42 - and answer the questions so we can understand and reproduce the 43 - problematic behavior. 103 + Pull requests should not be the place for architecture discussions. 44 104 45 - To show us that the issue you are having is in Gitea itself, please 46 - write clear, concise instructions so we can reproduce the behavior— 47 - even if it seems obvious. The more detailed and specific you are, 48 - the faster we can fix the issue. Check out [How to Report Bugs 49 - Effectively](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html). 105 + ## Building Gitea 50 106 51 - Please be kind, remember that Gitea comes at no cost to you, and you're 52 - getting free help. 107 + See the [development setup instructions](https://docs.gitea.com/development/hacking-on-gitea). 53 108 54 - ## Discuss your design 109 + ## Dependencies 55 110 56 - The project welcomes submissions. If you want to change or add something, 57 - please let everyone know what you're working on—[file an issue](https://github.com/go-gitea/gitea/issues/new)! 58 - Significant changes must go through the change proposal process 59 - before they can be accepted. To create a proposal, file an issue with 60 - your proposed changes documented, and make sure to note in the title 61 - of the issue that it is a proposal. 111 + ### Backend 62 112 63 - This process gives everyone a chance to validate the design, helps 64 - prevent duplication of effort, and ensures that the idea fits inside 65 - the goals for the project and tools. It also checks that the design is 66 - sound before code is written; the code review tool is not the place for 67 - high-level discussions. 113 + Go dependencies are managed using [Go Modules](https://golang.org/cmd/go/#hdr-Module_maintenance). \ 114 + You can find more details in the [go mod documentation](https://go.dev/ref/mod) and the [Go Modules Wiki](https://github.com/golang/go/wiki/Modules). 68 115 69 - ## Testing redux 116 + Pull requests should only modify `go.mod` and `go.sum` where it is related to your change, be it a bugfix or a new feature. \ 117 + Apart from that, these files should only be modified by Pull Requests whose only purpose is to update dependencies. 70 118 71 - Before submitting a pull request, run all the tests for the whole tree 72 - to make sure your changes don't cause regression elsewhere. 119 + The `go.mod`, `go.sum` update needs to be justified as part of the PR description, 120 + and must be verified by the reviewers and/or merger to always reference 121 + an existing upstream commit. 122 + 123 + ### Frontend 124 + 125 + For the frontend, we use [npm](https://www.npmjs.com/). 126 + 127 + The same restrictions apply for frontend dependencies as for backend dependencies, with the exceptions that the files for it are `package.json` and `package-lock.json`, and that new versions must always reference an existing version. 128 + 129 + ## Design guideline 130 + 131 + Depending on your change, please read the 132 + 133 + - [backend development guideline](https://docs.gitea.com/contributing/guidelines-backend) 134 + - [frontend development guideline](https://docs.gitea.com/contributing/guidelines-frontend) 135 + - [refactoring guideline](https://docs.gitea.com/contributing/guidelines-refactoring) 136 + 137 + ## Styleguide 138 + 139 + You should always run `make fmt` before committing to conform to Gitea's styleguide. 140 + 141 + ## Copyright 142 + 143 + New code files that you contribute should use the standard copyright header: 144 + 145 + ``` 146 + // Copyright <current year> The Gitea Authors. All rights reserved. 147 + // SPDX-License-Identifier: MIT 148 + ``` 149 + 150 + Afterwards, copyright should only be modified when the copyright author changes. 151 + 152 + ## Testing 153 + 154 + Before submitting a pull request, run all tests to make sure your changes don't cause a regression elsewhere. 73 155 74 156 Here's how to run the test suite: 75 157 ··· 77 159 78 160 | | | 79 161 | :-------------------- | :---------------------------------------------------------------- | 80 - |``make lint`` | lint everything (not suggest if you only change one type code) | 162 + |``make lint`` | lint everything (not needed if you only change the front- **or** backend) | 81 163 |``make lint-frontend`` | lint frontend files | 82 164 |``make lint-backend`` | lint backend files | 83 165 84 - - run test code (Suggest run in Linux) 166 + - run tests (we suggest running them on Linux) 167 + 168 + | Command | Action | | 169 + | :------------------------------------- | :----------------------------------------------- | ------------ | 170 + |``make test[\#SpecificTestName]`` | run unit test(s) | 171 + |``make test-sqlite[\#SpecificTestName]``| run [integration](tests/integration) test(s) for SQLite |[More details](tests/integration/README.md) | 172 + |``make test-e2e-sqlite[\#SpecificTestName]``| run [end-to-end](tests/e2e) test(s) for SQLite |[More details](tests/e2e/README.md) | 173 + 174 + ## Translation 175 + 176 + All translation work happens on [Crowdin](https://crowdin.com/project/gitea). 177 + The only translation that is maintained in this repository is [the English translation](https://github.com/go-gitea/gitea/blob/master/options/locale/locale_en-US.ini). 178 + It is synced regularly with Crowdin. \ 179 + Other locales on main branch **should not** be updated manually as they will be overwritten with each sync. \ 180 + Once a language has reached a **satisfactory percentage** of translated keys (~25%), it will be synced back into this repo and included in the next released version. 181 + 182 + The tool `go run build/backport-locale.go` can be used to backport locales from the main branch to release branches that were missed. 183 + 184 + ## Code review 185 + 186 + ### Pull request format 187 + 188 + Please try to make your pull request easy to review for us. \ 189 + For that, please read the [*Best Practices for Faster Reviews*](https://github.com/kubernetes/community/blob/261cb0fd089b64002c91e8eddceebf032462ccd6/contributors/guide/pull-requests.md#best-practices-for-faster-reviews) guide. \ 190 + It has lots of useful tips for any project you may want to contribute to. \ 191 + Some of the key points: 192 + 193 + - Make small pull requests. \ 194 + The smaller, the faster to review and the more likely it will be merged soon. 195 + - Don't make changes unrelated to your PR. \ 196 + Maybe there are typos on some comments, maybe refactoring would be welcome on a function... \ 197 + but if that is not related to your PR, please make *another* PR for that. 198 + - Split big pull requests into multiple small ones. \ 199 + An incremental change will be faster to review than a huge PR. 200 + - Allow edits by maintainers. This way, the maintainers will take care of merging the PR later on instead of you. 85 201 86 - | | | 87 - | :------------------------------------- | :----------------------------------------------- | 88 - |``make test[\#TestSpecificName]`` | run unit test | 89 - |``make test-sqlite[\#TestSpecificName]``| run [integration](tests/integration) test for SQLite | 90 - |[More details about integration tests](tests/integration/README.md) | 91 - |``make test-e2e-sqlite[\#TestSpecificFileName]``| run [end-to-end](tests/e2e) test for SQLite | 92 - |[More details about e2e tests](tests/e2e/README.md) | 202 + ### PR title and summary 93 203 94 - ## Vendoring 204 + In the PR title, describe the problem you are fixing, not how you are fixing it. \ 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. \ 207 + Keep this summary up-to-date as the PR evolves. \ 208 + 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 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 95 211 96 - We manage dependencies via [Go Modules](https://golang.org/cmd/go/#hdr-Module_maintenance), more details: [go mod](https://go.dev/ref/mod). 212 + ```text 213 + Fixes/Closes/Resolves #<ISSUE_NR_X>. 214 + Fixes/Closes/Resolves #<ISSUE_NR_Y>. 215 + ``` 97 216 98 - Pull requests should only include `go.mod`, `go.sum` updates if they are part of 99 - the same change, be it a bugfix or a feature addition. 217 + to your summary. \ 218 + Each issue that will be closed must stand on a separate line. 219 + 220 + ### Milestone 100 221 101 - The `go.mod`, `go.sum` update needs to be justified as part of the PR description, 102 - and must be verified by the reviewers and/or merger to always reference 103 - an existing upstream commit. 222 + A PR should only be assigned to a milestone if it will likely be merged into the given version. \ 223 + As a rule of thumb, assume that a PR will stay open for an additional month for every 100 added lines. \ 224 + PRs without a milestone may not be merged. 225 + 226 + ### Labels 104 227 105 - You can find more information on how to get started with it on the [Modules Wiki](https://github.com/golang/go/wiki/Modules). 228 + Every PR should be labeled correctly with every label that applies. \ 229 + This includes especially the distinction between `bug` (fixing existing functionality), `feature` (new functionality), `enhancement` (upgrades for existing functionality), and `refactoring` (improving the internal code structure without changing the output (much)). \ 230 + Furthermore, 106 231 107 - ## Translation 232 + - the amount of pending required approvals 233 + - whether this PR is `blocked`, a `backport` or `breaking` 234 + - if it targets the `ui` or `api` 235 + - if it increases the application `speed` 236 + - reduces `memory usage` 108 237 109 - We do all translation work inside [Crowdin](https://crowdin.com/project/gitea). 110 - The only translation that is maintained in this Git repository is 111 - [`en_US.ini`](https://github.com/go-gitea/gitea/blob/master/options/locale/locale_en-US.ini) 112 - and is synced regularly to Crowdin. Once a translation has reached 113 - A SATISFACTORY PERCENTAGE it will be synced back into this repo and 114 - included in the next released version. 238 + are oftentimes notable labels. 115 239 116 - ## Building Gitea 240 + ### Breaking PRs 117 241 118 - See the [hacking instructions](https://docs.gitea.io/en-us/hacking-on-gitea/). 242 + #### What is a breaking PR? 119 243 120 - ## Code review 244 + A PR is breaking if it meets one of the following criteria: 121 245 122 - Changes to Gitea must be reviewed before they are accepted—no matter who 123 - makes the change, even if they are an owner or a maintainer. We use GitHub's 124 - pull request workflow to do that. Every PR is reviewed by at least 2 maintainers. 246 + - It changes API output in an incompatible way for existing users 247 + - It removes a setting that an admin could previously set (i.e. via `app.ini`) 248 + - An admin must do something manually to restore the old behavior 125 249 126 - Please try to make your pull request easy to review for us. And, please read 127 - the *[How to get faster PR reviews](https://github.com/kubernetes/community/blob/261cb0fd089b64002c91e8eddceebf032462ccd6/contributors/guide/pull-requests.md#best-practices-for-faster-reviews)* guide; 128 - it has lots of useful tips for any project you may want to contribute. 129 - Some of the key points: 250 + In particular, this means that adding new settings is not breaking.\ 251 + Changing the default value of a setting or replacing the setting with another one is breaking, however. 130 252 131 - - Make small pull requests. The smaller, the faster to review and the 132 - more likely it will be merged soon. 133 - - Don't make changes unrelated to your PR. Maybe there are typos on 134 - some comments, maybe refactoring would be welcome on a function... but 135 - if that is not related to your PR, please make *another* PR for that. 136 - - Split big pull requests into multiple small ones. An incremental change 137 - will be faster to review than a huge PR. 138 - - Use the first comment as a summary explainer of your PR and you should keep this up-to-date as the PR evolves. 253 + #### How to handle breaking PRs? 139 254 140 - If your PR could cause a breaking change you must add a BREAKING section to this comment e.g.: 255 + If your PR has a breaking change, you must add a `BREAKING` section to your PR summary, e.g. 141 256 142 257 ``` 143 258 ## :warning: BREAKING :warning: 144 259 ``` 145 260 146 - To explain how this could affect users and how to mitigate these changes. 261 + To explain how this will affect users and how to mitigate these changes. 262 + 263 + ### Maintaining open PRs 264 + 265 + The moment you create a non-draft PR or the moment you convert a draft PR to a non-draft PR is the moment code review starts for it. \ 266 + Once that happens, do not rebase or squash your branch anymore as it makes it difficult to review the new changes. \ 267 + Merge the base branch into your branch only when you really need to, i.e. because of conflicting changes in the mean time. \ 268 + This reduces unnecessary CI runs. \ 269 + Don't worry about merge commits messing up your commit history as every PR will be squash merged. \ 270 + This means that all changes are joined into a single new commit whose message is as described below. 271 + 272 + ### Getting PRs merged 273 + 274 + Changes to Gitea must be reviewed before they are accepted — no matter who 275 + makes the change, even if they are an owner or a maintainer. \ 276 + The only exception are critical bugs that prevent Gitea from being compiled or started. \ 277 + Specifically, we require two approvals from maintainers for every PR. \ 278 + Once this criteria has been met, your PR receives the `lgtm/done` label. \ 279 + From this point on, your only responsibility is to fix merge conflicts or respond to/implement requests by maintainers. \ 280 + It is the responsibility of the maintainers from this point to get your PR merged. 281 + 282 + If a PR has the `lgtm/done` label and there are no open discussions or merge conflicts anymore, any maintainer can add the `reviewed/wait-merge` label. \ 283 + This label means that the PR is part of the merge queue and will be merged as soon as possible. \ 284 + The merge queue will be cleared in the order of the list below: 285 + 286 + <https://github.com/go-gitea/gitea/pulls?q=is%3Apr+label%3Areviewed%2Fwait-merge+sort%3Acreated-asc+is%3Aopen> 287 + 288 + Gitea uses it's own tool, the <https://github.com/GiteaBot/gitea-backporter> to automate parts of the review process. \ 289 + This tool does the things listed below automatically: 290 + 291 + - create a backport PR if needed once the initial PR was merged 292 + - remove the PR from the merge queue after the PR merged 293 + - keep the oldest branch in the merge queue up to date with merges 147 294 148 - Once code review starts on your PR, do not rebase nor squash your branch as it makes it 149 - difficult to review the new changes. Only if there is a need, sync your branch by merging 150 - the base branch into yours. Don't worry about merge commits messing up your tree as 151 - the final merge process squashes all commits into one, with the visible commit message (first 152 - line) being the PR title + PR index and description being the PR's first comment. 295 + ### Final call 296 + 297 + If a PR has been ignored for more than 7 days with no comments or reviews, and the author or any maintainer believes it will not survive a long wait (such as a refactoring PR), they can send "final call" to the TOC by mentioning them in a comment. 153 298 154 - Once your PR gets the `lgtm/done` label, don't worry about keeping it up-to-date or breaking 155 - builds (unless there's a merge conflict or a request is made by a maintainer to make 156 - modifications). It is the maintainer team's responsibility from this point to get it merged. 299 + After another 7 days, if there is still zero approval, this is considered a polite refusal, and the PR will be closed to avoid wasting further time. Therefore, the "final call" has a cost, and should be used cautiously. 157 300 158 - ## Styleguide 301 + However, if there are no objections from maintainers, the PR can be merged with only one approval from the TOC (not the author). 159 302 160 - For imports you should use the following format (*without* the comments) 303 + ### Commit messages 161 304 162 - ```go 163 - import ( 164 - // stdlib 165 - "fmt" 166 - "math" 305 + Mergers are able and required to rewrite the PR title and summary (the first comment of a PR) so that it can produce an easily understandable commit message if necessary. \ 306 + The final commit message should no longer contain any uncertainty such as `hopefully, <x> won't happen anymore`. Replace uncertainty with certainty. 167 307 168 - // local packages 169 - "code.gitea.io/gitea/models" 170 - "code.gitea.io/sdk/gitea" 308 + #### PR Co-authors 171 309 172 - // external packages 173 - "github.com/foo/bar" 174 - "gopkg.io/baz.v1" 175 - ) 176 - ``` 310 + A person counts as a PR co-author the moment they (co-)authored a commit that is not simply a `Merge base branch into branch` commit. \ 311 + Mergers are required to remove such "false-positive" co-authors when writing the commit message. \ 312 + The true co-authors must remain in the commit message. 177 313 178 - ## Design guideline 314 + #### PRs targeting `main` 179 315 180 - To maintain understandable code and avoid circular dependencies it is important to have a good structure of the code. The Gitea code is divided into the following parts: 316 + The commit message of PRs targeting `main` is always 181 317 182 - - **models:** Contains the data structures used by xorm to construct database tables. It also contains supporting functions to query and update the database. Dependencies to other code in Gitea should be avoided although some modules might be needed (for example for logging). 183 - - **models/fixtures:** Sample model data used in integration tests. 184 - - **models/migrations:** Handling of database migrations between versions. PRs that changes a database structure shall also have a migration step. 185 - - **modules:** Different modules to handle specific functionality in Gitea. Shall only depend on other modules but not other packages (models, services). 186 - - **public:** Frontend files (javascript, images, css, etc.) 187 - - **routers:** Handling of server requests. As it uses other Gitea packages to serve the request, other packages (models, modules or services) shall not depend on routers. 188 - - **services:** Support functions for common routing operations. Uses models and modules to handle the request. 189 - - **templates:** Golang templates for generating the html output. 190 - - **tests/e2e:** End to end tests 191 - - **tests/integration:** Integration tests 192 - - **tests/gitea-repositories-meta:** Sample repos used in integration tests. Adding a new repo requires editing `models/fixtures/repositories.yml` and `models/fixtures/repo_unit.yml` to match. 193 - - **tests/gitea-lfs-meta:** Sample LFS objects used in integration tests. Adding a new object requires editing `models/fixtures/lfs_meta_object.yml` to match. 194 - - **vendor:** External code that Gitea depends on. 318 + ```bash 319 + $PR_TITLE ($PR_INDEX) 195 320 196 - ## Documentation 321 + $REWRITTEN_PR_SUMMARY 322 + ``` 197 323 198 - If you add a new feature or change an existing aspect of Gitea, the documentation for that feature must be created or updated. 324 + #### Backport PRs 199 325 200 - ## API v1 326 + The commit message of backport PRs is always 201 327 202 - The API is documented by [swagger](http://try.gitea.io/api/swagger) and is based on [GitHub API v3](https://developer.github.com/v3/). 328 + ```bash 329 + $PR_TITLE ($INITIAL_PR_INDEX) ($BACKPORT_PR_INDEX) 203 330 204 - Thus, Gitea´s API should use the same endpoints and fields as GitHub´s API as far as possible, unless there are good reasons to deviate. 331 + $REWRITTEN_PR_SUMMARY 332 + ``` 205 333 206 - If Gitea provides functionality that GitHub does not, a new endpoint can be created. 334 + ## Documentation 207 335 208 - If information is provided by Gitea that is not provided by the GitHub API, a new field can be used that doesn't collide with any GitHub fields. 336 + If you add a new feature or change an existing aspect of Gitea, the documentation for that feature must be created or updated in the same PR. 209 337 210 - Updating an existing API should not remove existing fields unless there is a really good reason to do so. 338 + ## API v1 211 339 212 - The same applies to status responses. If you notice a problem, feel free to leave a comment in the code for future refactoring to APIv2 (which is currently not planned). 340 + The API is documented by [swagger](http://try.gitea.io/api/swagger) and is based on [the GitHub API](https://docs.github.com/en/rest). 213 341 214 - All expected results (errors, success, fail messages) should be documented 215 - ([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/repo/issue.go#L319-L327)). 342 + ### GitHub API compatability 216 343 217 - All JSON input types must be defined as a struct in [modules/structs/](modules/structs/) 218 - ([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/modules/structs/issue.go#L76-L91)) 219 - and referenced in 220 - [routers/api/v1/swagger/options.go](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/swagger/options.go). 344 + Gitea's API should use the same endpoints and fields as the GitHub API as far as possible, unless there are good reasons to deviate. \ 345 + If Gitea provides functionality that GitHub does not, a new endpoint can be created. \ 346 + If information is provided by Gitea that is not provided by the GitHub API, a new field can be used that doesn't collide with any GitHub fields. \ 347 + Updating an existing API should not remove existing fields unless there is a really good reason to do so. \ 348 + The same applies to status responses. If you notice a problem, feel free to leave a comment in the code for future refactoring to API v2 (which is currently not planned). 221 349 222 - They can then be used like the following: 223 - ([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/repo/issue.go#L318)). 350 + ### Adding/Maintaining API routes 224 351 225 - All JSON responses must be defined as a struct in [modules/structs/](modules/structs/) 226 - ([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/modules/structs/issue.go#L36-L68)) 227 - and referenced in its category in [routers/api/v1/swagger/](routers/api/v1/swagger/) 228 - ([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/swagger/issue.go#L11-L16)) 352 + All expected results (errors, success, fail messages) must be documented ([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/repo/issue.go#L319-L327)). \ 353 + All JSON input types must be defined as a struct in [modules/structs/](modules/structs/) ([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/modules/structs/issue.go#L76-L91)) \ 354 + and referenced in [routers/api/v1/swagger/options.go](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/swagger/options.go). \ 355 + They can then be used like [this example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/repo/issue.go#L318). \ 356 + All JSON responses must be defined as a struct in [modules/structs/](modules/structs/) ([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/modules/structs/issue.go#L36-L68)) \ 357 + and referenced in its category in [routers/api/v1/swagger/](routers/api/v1/swagger/) ([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/swagger/issue.go#L11-L16)) \ 358 + They can be used like [this example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/repo/issue.go#L277-L279). 229 359 230 - They can be used like the following: 231 - ([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/repo/issue.go#L277-L279)) 360 + ### When to use what HTTP method 232 361 233 362 In general, HTTP methods are chosen as follows: 234 363 235 - - **GET** endpoints return requested object and status **OK (200)** 236 - - **DELETE** endpoints return status **No Content (204)** 237 - - **POST** endpoints return status **Created (201)**, used to **create** new objects (e.g. a User) 238 - - **PUT** endpoints return status **No Content (204)**, used to **add/assign** existing Objects (e.g. User) to something (e.g. Org-Team) 239 - - **PATCH** endpoints return changed object and status **OK (200)**, used to **edit/change** an existing object 364 + - **GET** endpoints return the requested object(s) and status **OK (200)** 365 + - **DELETE** endpoints return the status **No Content (204)** and no content either 366 + - **POST** endpoints are used to **create** new objects (e.g. a User) and return the status **Created (201)** and the created object 367 + - **PUT** endpoints are used to **add/assign** existing Objects (e.g. a user to a team) and return the status **No Content (204)** and no content either 368 + - **PATCH** endpoints are used to **edit/change** an existing object and return the changed object and the status **OK (200)** 240 369 241 - An endpoint which changes/edits an object expects all fields to be optional (except ones to identify the object, which are required). 370 + ### Requirements for API routes 242 371 243 - ### Endpoints returning lists should 372 + All parameters of endpoints changing/editing an object must be optional (except the ones to identify the object, which are required). 373 + 374 + Endpoints returning lists must 244 375 245 376 - support pagination (`page` & `limit` options in query) 246 377 - set `X-Total-Count` header via **SetTotalCountHeader** ([example](https://github.com/go-gitea/gitea/blob/7aae98cc5d4113f1e9918b7ee7dd09f67c189e3e/routers/api/v1/repo/issue.go#L444)) 247 378 248 379 ## Backports and Frontports 249 380 250 - Occasionally backports of PRs are required. 381 + ### What is backported? 251 382 252 - The backported PR title should be: 383 + We backport PRs given the following circumstances: 384 + 385 + 1. Feature freeze is active, but `<version>-rc0` has not been released yet. Here, we backport as much as possible.  386 + 2. `rc0` has been released. Here, we only backport bug- and security-fixes, and small enhancements. Large PRs such as refactors are not backported anymore.  387 + 3. We never backport new features. 388 + 4. We never backport breaking changes except when 389 + 1. The breaking change has no effect on the vast majority of users 390 + 2. The component triggering the breaking change is marked as experimental 391 + 392 + ### How to backport? 393 + 394 + In the past, it was necessary to manually backport your PRs. \ 395 + Now, that's not a requirement anymore as our [backport bot](https://github.com/GiteaBot) tries to create backports automatically once the PR is merged when the PR 396 + 397 + - does not have the label `backport/manual` 398 + - has the label `backport/<version>` 399 + 400 + The `backport/manual` label signifies either that you want to backport the change yourself, or that there were conflicts when backporting, thus you **must** do it yourself. 401 + 402 + ### Format of backport PRs 403 + 404 + The title of backport PRs should be 253 405 254 406 ``` 255 - Title of backported PR (#ORIGINAL_PR_NUMBER) 407 + <original PR title> (#<original pr number>) 256 408 ``` 257 409 258 - The first two lines of the summary of the backporting PR should be: 410 + The first two lines of the summary of the backporting PR should be 259 411 260 412 ``` 261 - Backport #ORIGINAL_PR_NUMBER 413 + Backport #<original pr number> 262 414 263 415 ``` 264 416 265 - with the rest of the summary matching the original PR. Similarly for frontports 417 + with the rest of the summary and labels matching the original PR. 266 418 267 - --- 419 + ### Frontports 268 420 269 - A command to help create backports can be found in `contrib/backport` and can be installed (from inside the gitea repo root directory) using: 270 - 271 - ```bash 272 - go install contrib/backport/backport.go 273 - ``` 421 + Frontports behave exactly as described above for backports. 274 422 275 423 ## Developer Certificate of Origin (DCO) 276 424 277 - We consider the act of contributing to the code by submitting a Pull 278 - Request as the "Sign off" or agreement to the certifications and terms 279 - of the [DCO](DCO) and [MIT license](LICENSE). No further action is required. 280 - Additionally you could add a line at the end of your commit message. 425 + We consider the act of contributing to the code by submitting a Pull Request as the "Sign off" or agreement to the certifications and terms of the [DCO](DCO) and [MIT license](LICENSE). \ 426 + No further action is required. \ 427 + You can also decide to sign off your commits by adding the following line at the end of your commit messages: 281 428 282 429 ``` 283 430 Signed-off-by: Joe Smith <joe.smith@email.com> 284 431 ``` 285 432 286 - If you set your `user.name` and `user.email` Git configs, you can add the 287 - line to the end of your commit automatically with `git commit -s`. 433 + If you set the `user.name` and `user.email` Git config options, you can add the line to the end of your commits automatically with `git commit -s`. 288 434 289 435 We assume in good faith that the information you provide is legally binding. 290 436 291 437 ## Release Cycle 292 438 293 - We adopted a release schedule to streamline the process of working 294 - on, finishing, and issuing releases. The overall goal is to make a 295 - minor release every three or four months, which breaks down into two or three months of 296 - general development followed by one month of testing and polishing 297 - known as the release freeze. All the feature pull requests should be 439 + We adopted a release schedule to streamline the process of working on, finishing, and issuing releases. \ 440 + The overall goal is to make a major release every three or four months, which breaks down into two or three months of general development followed by one month of testing and polishing known as the release freeze. \ 441 + All the feature pull requests should be 298 442 merged before feature freeze. And, during the frozen period, a corresponding 299 443 release branch is open for fixes backported from main branch. Release candidates 300 444 are made during this period for user testing to 301 445 obtain a final version that is maintained in this branch. 302 446 303 - Major release cycles are seasonal. They always begin on the 25th and end on 304 - the 24th (i.e., the 25th of December to March 24th). 305 - 306 447 During a development cycle, we may also publish any necessary minor releases 307 448 for the previous version. For example, if the latest, published release is 308 449 v1.2, then minor changes for the previous release—e.g., v1.1.0 -> v1.1.1—are 309 450 still possible. 310 451 311 - The previous release gets fixes for: 312 - 313 - - Security issues 314 - - Critical bugs 315 - - Regressions 316 - - Build issues 317 - - Necessary enhancements (including necessary UI/UX fixes) 318 - 319 - The backported fixes should avoid breaking downgrade between minor releases as much as possible. 320 - 321 452 ## Maintainers 322 453 323 - To make sure every PR is checked, we have [team 324 - maintainers](MAINTAINERS). Every PR **MUST** be reviewed by at least 325 - two maintainers (or owners) before it can get merged. A maintainer 326 - should be a contributor of Gitea (or Gogs) and contributed at least 454 + To make sure every PR is checked, we have [maintainers](MAINTAINERS). \ 455 + Every PR **must** be reviewed by at least two maintainers (or owners) before it can get merged. \ 456 + For refactoring PRs after a week and documentation only PRs, the approval of only one maintainer is enough. \ 457 + A maintainer should be a contributor of Gitea and contributed at least 327 458 4 accepted PRs. A contributor should apply as a maintainer in the 328 - [Discord](https://discord.gg/NsatcWJ) #develop channel. The owners 329 - or the team maintainers may invite the contributor. A maintainer 459 + [Discord](https://discord.gg/Gitea) `#develop` channel. The team maintainers may invite the contributor. A maintainer 330 460 should spend some time on code reviews. If a maintainer has no 331 461 time to do that, they should apply to leave the maintainers team 332 462 and we will give them the honor of being a member of the [advisors ··· 340 470 https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ 341 471 https://help.github.com/articles/signing-commits-with-gpg/ 342 472 343 - ## Owners 473 + ## Technical Oversight Committee (TOC) 344 474 345 - Since Gitea is a pure community organization without any company support, 346 - to keep the development healthy we will elect three owners every year. All 347 - contributors may vote to elect up to three candidates, one of which will 348 - be the main owner, and the other two the assistant owners. When the new 349 - owners have been elected, the old owners will give up ownership to the 350 - newly elected owners. If an owner is unable to do so, the other owners 351 - will assist in ceding ownership to the newly elected owners. 352 - For security reasons, Owners or any account with write access (like a bot) 353 - must use 2FA. 475 + At the start of 2023, the `Owners` team was dissolved. Instead, the governance charter proposed a technical oversight committee (TOC) which expands the ownership team of the Gitea project from three elected positions to six positions. Three positions would be elected as it has been over the past years, and the other three would consist of appointed members from the Gitea company. 476 + https://blog.gitea.io/2023/02/gitea-quarterly-report-23q1/ 477 + 478 + When the new community members have been elected, the old members will give up ownership to the newly elected members. For security reasons, TOC members or any account with write access (like a bot) must use 2FA. 354 479 https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ 355 480 356 - After the election, the new owners should proactively agree 357 - with our [CONTRIBUTING](CONTRIBUTING.md) requirements in the 358 - [Discord](https://discord.gg/NsatcWJ) #general channel. Below are the 359 - words to speak: 481 + ### Current TOC members 360 482 361 - ``` 362 - I'm honored to having been elected an owner of Gitea, I agree with 363 - [CONTRIBUTING](CONTRIBUTING.md). I will spend part of my time on Gitea 364 - and lead the development of Gitea. 365 - ``` 483 + - 2023-01-01 ~ 2023-12-31 - https://blog.gitea.io/2023/02/gitea-quarterly-report-23q1/ 484 + - Company 485 + - [Jason Song](https://gitea.com/wolfogre) <i@wolfogre.com> 486 + - [Lunny Xiao](https://gitea.com/lunny) <xiaolunwen@gmail.com> 487 + - [Matti Ranta](https://gitea.com/techknowlogick) <techknowlogick@gitea.io> 488 + - Community 489 + - [6543](https://gitea.com/6543) <6543@obermui.de> 490 + - [Andrew Thornton](https://gitea.com/zeripath) <art27@cantab.net> 491 + - [John Olheiser](https://gitea.com/jolheiser) <john.olheiser@gmail.com> 366 492 367 - To honor the past owners, here's the history of the owners and the time 368 - they served: 493 + ### Previous TOC/owners members 369 494 370 - - 2022-01-01 ~ 2022-12-31 - https://github.com/go-gitea/gitea/issues/17872 371 - - [Lunny Xiao](https://gitea.com/lunny) <xiaolunwen@gmail.com> 372 - - [Matti Ranta](https://gitea.com/techknowlogick) <techknowlogick@gitea.io> 373 - - [Andrew Thornton](https://gitea.com/zeripath) <art27@cantab.net> 495 + Here's the history of the owners and the time they served: 374 496 375 - - 2021-01-01 ~ 2021-12-31 - https://github.com/go-gitea/gitea/issues/13801 376 - - [Lunny Xiao](https://gitea.com/lunny) <xiaolunwen@gmail.com> 377 - - [Lauris Bukšis-Haberkorns](https://gitea.com/lafriks) <lauris@nix.lv> 378 - - [Matti Ranta](https://gitea.com/techknowlogick) <techknowlogick@gitea.io> 497 + - [Lunny Xiao](https://gitea.com/lunny) - 2016, 2017, [2018](https://github.com/go-gitea/gitea/issues/3255), [2019](https://github.com/go-gitea/gitea/issues/5572), [2020](https://github.com/go-gitea/gitea/issues/9230), [2021](https://github.com/go-gitea/gitea/issues/13801), [2022](https://github.com/go-gitea/gitea/issues/17872) 498 + - [Kim Carlbäcker](https://github.com/bkcsoft) - 2016, 2017 499 + - [Thomas Boerger](https://gitea.com/tboerger) - 2016, 2017 500 + - [Lauris Bukšis-Haberkorns](https://gitea.com/lafriks) - [2018](https://github.com/go-gitea/gitea/issues/3255), [2019](https://github.com/go-gitea/gitea/issues/5572), [2020](https://github.com/go-gitea/gitea/issues/9230), [2021](https://github.com/go-gitea/gitea/issues/13801) 501 + - [Matti Ranta](https://gitea.com/techknowlogick) - [2019](https://github.com/go-gitea/gitea/issues/5572), [2020](https://github.com/go-gitea/gitea/issues/9230), [2021](https://github.com/go-gitea/gitea/issues/13801), [2022](https://github.com/go-gitea/gitea/issues/17872) 502 + - [Andrew Thornton](https://gitea.com/zeripath) - [2020](https://github.com/go-gitea/gitea/issues/9230), [2021](https://github.com/go-gitea/gitea/issues/13801), [2022](https://github.com/go-gitea/gitea/issues/17872) 379 503 380 - - 2020-01-01 ~ 2020-12-31 - https://github.com/go-gitea/gitea/issues/9230 381 - - [Lunny Xiao](https://gitea.com/lunny) <xiaolunwen@gmail.com> 382 - - [Lauris Bukšis-Haberkorns](https://gitea.com/lafriks) <lauris@nix.lv> 383 - - [Matti Ranta](https://gitea.com/techknowlogick) <techknowlogick@gitea.io> 504 + ## Governance Compensation 384 505 385 - - 2019-01-01 ~ 2019-12-31 - https://github.com/go-gitea/gitea/issues/5572 386 - - [Lunny Xiao](https://github.com/lunny) <xiaolunwen@gmail.com> 387 - - [Lauris Bukšis-Haberkorns](https://github.com/lafriks) <lauris@nix.lv> 388 - - [Matti Ranta](https://github.com/techknowlogick) <techknowlogick@gitea.io> 506 + Each member of the community elected TOC will be granted $500 each month as compensation for their work. 389 507 390 - - 2018-01-01 ~ 2018-12-31 - https://github.com/go-gitea/gitea/issues/3255 391 - - [Lunny Xiao](https://github.com/lunny) <xiaolunwen@gmail.com> 392 - - [Lauris Bukšis-Haberkorns](https://github.com/lafriks) <lauris@nix.lv> 393 - - [Kim Carlbäcker](https://github.com/bkcsoft) <kim.carlbacker@gmail.com> 508 + Furthermore, any community release manager for a specific release or LTS will be compensated $500 for the delivery of said release. 394 509 395 - - 2016-11-04 ~ 2017-12-31 396 - - [Lunny Xiao](https://github.com/lunny) <xiaolunwen@gmail.com> 397 - - [Thomas Boerger](https://github.com/tboerger) <thomas@webhippie.de> 398 - - [Kim Carlbäcker](https://github.com/bkcsoft) <kim.carlbacker@gmail.com> 510 + These funds will come from community sources like the OpenCollective rather than directly from the company. 511 + Only non-company members are eligible for this compensation, and if a member of the community TOC takes the responsibility of release manager, they would only be compensated for their TOC duties. 512 + Gitea Ltd employees are not eligible to receive any funds from the OpenCollective unless it is reimbursement for a purchase made for the Gitea project itself. 513 + 514 + ## TOC & Working groups 515 + 516 + With Gitea covering many projects outside of the main repository, several groups will be created to help focus on specific areas instead of requiring maintainers to be a jack-of-all-trades. Maintainers are of course more than welcome to be part of multiple groups should they wish to contribute in multiple places. 517 + 518 + The currently proposed groups are: 519 + 520 + - **Core Group**: maintain the primary Gitea repository 521 + - **Integration Group**: maintain the Gitea ecosystem's related tools, including go-sdk/tea/changelog/bots etc. 522 + - **Documentation Group**: maintain related documents and repositories 523 + - **Translation Group**: coordinate with translators and maintain translations 524 + - **Security Group**: managed by TOC directly, members are decided by TOC, maintains security patches/responsible for security items 525 + 526 + ## Roadmap 527 + 528 + Each year a roadmap will be discussed with the entire Gitea maintainers team, and feedback will be solicited from various stakeholders. 529 + TOC members need to review the roadmap every year and work together on the direction of the project. 530 + 531 + When a vote is required for a proposal or other change, the vote of community elected TOC members count slightly more than the vote of company elected TOC members. With this approach, we both avoid ties and ensure that changes align with the mission statement and community opinion. 532 + 533 + You can visit our roadmap on the wiki. 399 534 400 535 ## Versions 401 536 402 537 Gitea has the `main` branch as a tip branch and has version branches 403 - such as `release/v0.9`. `release/v0.9` is a release branch and we will 404 - tag `v0.9.0` for binary download. If `v0.9.0` has bugs, we will accept 405 - pull requests on the `release/v0.9` branch and publish a `v0.9.1` tag, 538 + such as `release/v1.19`. `release/v1.19` is a release branch and we will 539 + tag `v1.19.0` for binary download. If `v1.19.0` has bugs, we will accept 540 + pull requests on the `release/v1.19` branch and publish a `v1.19.1` tag, 406 541 after bringing the bug fix also to the main branch. 407 542 408 543 Since the `main` branch is a tip version, if you wish to use Gitea ··· 426 561 - bump the version of https://dl.gitea.io/gitea/version.json 427 562 - merge the blog post PR 428 563 - announce the release in discord `#announcements` 429 - 430 - ## Copyright 431 - 432 - Code that you contribute should use the standard copyright header: 433 - 434 - ``` 435 - // Copyright <year> The Gitea Authors. All rights reserved. 436 - // SPDX-License-Identifier: MIT 437 - 438 - ``` 439 - 440 - Files in the repository contain copyright from the year they are added 441 - to the year they are last changed. If the copyright author is changed, 442 - just paste the header below the old one.

Configure Feed

Configure Feed