|
| 1 | +# Contribution Guidelines |
| 2 | + |
| 3 | +## Table of Contents |
| 4 | + |
| 5 | +- [Contribution Guidelines](#contribution-guidelines) |
| 6 | + - [Introduction](#introduction) |
| 7 | + - [Bug reports](#bug-reports) |
| 8 | + - [Discuss your design](#discuss-your-design) |
| 9 | + - [Testing redux](#testing-redux) |
| 10 | + - [Vendoring](#vendoring) |
| 11 | + - [Translation](#translation) |
| 12 | + - [Code review](#code-review) |
| 13 | + - [Styleguide](#styleguide) |
| 14 | + - [Sign-off your work](#sign-off-your-work) |
| 15 | + - [Release Cycle](#release-cycle) |
| 16 | + - [Maintainers](#maintainers) |
| 17 | + - [Owners](#owners) |
| 18 | + - [Versions](#versions) |
| 19 | + - [Copyright](#copyright) |
| 20 | + |
| 21 | +## Introduction |
| 22 | + |
| 23 | +This document explains how to contribute changes to the Gitea project. |
| 24 | +It assumes you have followed the |
| 25 | +[installation instructions](https://docs.gitea.io/en-us/). |
| 26 | +Sensitive security-related issues should be reported to |
| 27 | + |
| 28 | + |
| 29 | +For configuring IDE or code editor to develop Gitea see [IDE and code editor configuration](contrib/ide/) |
| 30 | + |
| 31 | +## Bug reports |
| 32 | + |
| 33 | +Please search the issues on the issue tracker with a variety of keywords |
| 34 | +to ensure your bug is not already reported. |
| 35 | + |
| 36 | +If unique, [open an issue](https://github.com/go-gitea/gitea/issues/new) |
| 37 | +and answer the questions so we can understand and reproduce the |
| 38 | +problematic behavior. |
| 39 | + |
| 40 | +To show us that the issue you are having is in Gitea itself, please |
| 41 | +write clear, concise instructions so we can reproduce the behavior— |
| 42 | +even if it seems obvious. The more detailed and specific you are, |
| 43 | +the faster we can fix the issue. Check out [How to Report Bugs |
| 44 | +Effectively](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html). |
| 45 | + |
| 46 | +Please be kind, remember that Gitea comes at no cost to you, and you're |
| 47 | +getting free help. |
| 48 | + |
| 49 | +## Discuss your design |
| 50 | + |
| 51 | +The project welcomes submissions. If you want to change or add something, |
| 52 | +please let everyone know what you're working on—[file an issue](https://github.com/go-gitea/gitea/issues/new)! |
| 53 | +Significant changes must go through the change proposal process |
| 54 | +before they can be accepted. To create a proposal, file an issue with |
| 55 | +your proposed changes documented, and make sure to note in the title |
| 56 | +of the issue that it is a proposal. |
| 57 | + |
| 58 | +This process gives everyone a chance to validate the design, helps |
| 59 | +prevent duplication of effort, and ensures that the idea fits inside |
| 60 | +the goals for the project and tools. It also checks that the design is |
| 61 | +sound before code is written; the code review tool is not the place for |
| 62 | +high-level discussions. |
| 63 | + |
| 64 | +## Testing redux |
| 65 | + |
| 66 | +Before sending code out for review, run all the tests for the |
| 67 | +whole tree to make sure the changes don't break other usage |
| 68 | +and keep the compatibility on upgrade. To make sure you are |
| 69 | +running the test suite exactly like we do, you should install |
| 70 | +the CLI for [Drone CI](https://github.com/drone/drone), as |
| 71 | +we are using the server for continous testing, following [these |
| 72 | +instructions](http://docs.drone.io/cli-installation/). After that, |
| 73 | +you can simply call `drone exec --local --build-event "pull_request"` within |
| 74 | +your working directory and it will try to run the test suite locally. |
| 75 | + |
| 76 | +## Vendoring |
| 77 | + |
| 78 | +We keep a cached copy of dependencies within the `vendor/` directory, |
| 79 | +managing updates via [dep](https://github.com/golang/dep). |
| 80 | + |
| 81 | +Pull requests should only include `vendor/` updates if they are part of |
| 82 | +the same change, be it a bugfix or a feature addition. |
| 83 | + |
| 84 | +The `vendor/` update needs to be justified as part of the PR description, |
| 85 | +and must be verified by the reviewers and/or merger to always reference |
| 86 | +an existing upstream commit. |
| 87 | + |
| 88 | +You can find more information on how to get started with it on the [dep project website](https://golang.github.io/dep/docs/introduction.html). |
| 89 | + |
| 90 | +## Translation |
| 91 | + |
| 92 | +We do all translation work inside [Crowdin](https://crowdin.com/project/gitea). |
| 93 | +The only translation that is maintained in this git repository is |
| 94 | +[`en_US.ini`](https://github.com/go-gitea/gitea/blob/master/options/locale/locale_en-US.ini) |
| 95 | +and is synced regularily to Crowdin. Once a translation has reached |
| 96 | +A SATISFACTORY PERCENTAGE it will be synced back into this repo and |
| 97 | +included in the next released version. |
| 98 | + |
| 99 | +## Building Gitea |
| 100 | + |
| 101 | +Generally, the go build tools are installed as-needed in the `Makefile`. |
| 102 | +An exception are the tools to build the CSS and images. |
| 103 | + |
| 104 | +- To build CSS: Install [Node.js](https://nodejs.org/en/download/package-manager) |
| 105 | + with `npm` and then run `npm install` and `make generate-stylesheets`. |
| 106 | +- To build Images: ImageMagick, inkscape and zopflipng binaries must be |
| 107 | + available in your `PATH` to run `make generate-images`. |
| 108 | + |
| 109 | +## Code review |
| 110 | + |
| 111 | +Changes to Gitea must be reviewed before they are accepted—no matter who |
| 112 | +makes the change, even if they are an owner or a maintainer. We use GitHub's |
| 113 | +pull request workflow to do that. And, we also use [LGTM](http://lgtm.co) |
| 114 | +to ensure every PR is reviewed by at least 2 maintainers. |
| 115 | + |
| 116 | +Please try to make your pull request easy to review for us. And, please read |
| 117 | +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; |
| 118 | +it has lots of useful tips for any project you may want to contribute. |
| 119 | +Some of the key points: |
| 120 | + |
| 121 | +* Make small pull requests. The smaller, the faster to review and the |
| 122 | + more likely it will be merged soon. |
| 123 | +* Don't make changes unrelated to your PR. Maybe there are typos on |
| 124 | + some comments, maybe refactoring would be welcome on a function... but |
| 125 | + if that is not related to your PR, please make *another* PR for that. |
| 126 | +* Split big pull requests into multiple small ones. An incremental change |
| 127 | + will be faster to review than a huge PR. |
| 128 | + |
| 129 | +## Styleguide |
| 130 | + |
| 131 | +For imports you should use the following format (_without_ the comments) |
| 132 | +```go |
| 133 | +import ( |
| 134 | + // stdlib |
| 135 | + "encoding/json" |
| 136 | + "fmt" |
| 137 | + |
| 138 | + // local packages |
| 139 | + "code.gitea.io/gitea/models" |
| 140 | + "code.gitea.io/sdk/gitea" |
| 141 | + |
| 142 | + // external packages |
| 143 | + "github.com/foo/bar" |
| 144 | + "gopkg.io/baz.v1" |
| 145 | +) |
| 146 | +``` |
| 147 | + |
| 148 | +## Sign-off your work |
| 149 | + |
| 150 | +The sign-off is a simple line at the end of the explanation for the |
| 151 | +patch. Your signature certifies that you wrote the patch or otherwise |
| 152 | +have the right to pass it on as an open-source patch. The rules are |
| 153 | +pretty simple: If you can certify [DCO](DCO), then you just add a line |
| 154 | +to every git commit message: |
| 155 | + |
| 156 | +``` |
| 157 | +Signed-off-by: Joe Smith <[email protected]> |
| 158 | +``` |
| 159 | + |
| 160 | +Please use your real name; we really dislike pseudonyms or anonymous |
| 161 | +contributions. We are in the open-source world without secrets. If you |
| 162 | +set your `user.name` and `user.email` git configs, you can sign-off your |
| 163 | +commit automatically with `git commit -s`. |
| 164 | + |
| 165 | +## Release Cycle |
| 166 | + |
| 167 | +We adopted a release schedule to streamline the process of working |
| 168 | +on, finishing, and issuing releases. The overall goal is to make a |
| 169 | +minor release every two months, which breaks down into one month of |
| 170 | +general development followed by one month of testing and polishing |
| 171 | +known as the release freeze. All the feature pull requests should be |
| 172 | +merged in the first month of one release period. And, during the frozen |
| 173 | +period, a corresponding release branch is open for fixes backported from |
| 174 | +master. Release candidates are made during this period for user testing to |
| 175 | +obtain a final version that is maintained in this branch. A release is |
| 176 | +maintained by issuing patch releases to only correct critical problems |
| 177 | +such as crashes or security issues. |
| 178 | + |
| 179 | +Major release cycles are bimonthly. They always begin on the 25th and end on |
| 180 | +the 24th (i.e., the 25th of December to February 24th). |
| 181 | + |
| 182 | +During a development cycle, we may also publish any necessary minor releases |
| 183 | +for the previous version. For example, if the latest, published release is |
| 184 | +v1.2, then minor changes for the previous release—e.g., v1.1.0 -> v1.1.1—are |
| 185 | +still possible. |
| 186 | + |
| 187 | +## Maintainers |
| 188 | + |
| 189 | +To make sure every PR is checked, we have [team |
| 190 | +maintainers](MAINTAINERS). Every PR **MUST** be reviewed by at least |
| 191 | +two maintainers (or owners) before it can get merged. A maintainer |
| 192 | +should be a contributor of Gitea (or Gogs) and contributed at least |
| 193 | +4 accepted PRs. A contributor should apply as a maintainer in the |
| 194 | +[Discord](https://discord.gg/NsatcWJ) #develop channel. The owners |
| 195 | +or the team maintainers may invite the contributor. A maintainer |
| 196 | +should spend some time on code reviews. If a maintainer has no |
| 197 | +time to do that, they should apply to leave the maintainers team |
| 198 | +and we will give them the honor of being a member of the [advisors |
| 199 | +team](https://github.com/orgs/go-gitea/teams/advisors). Of course, if |
| 200 | +an advisor has time to code review, we will gladly welcome them back |
| 201 | +to the maintainers team. If a maintainer is inactive for more than 3 |
| 202 | +months and forgets to leave the maintainers team, the owners may move |
| 203 | +him or her from the maintainers team to the advisors team. |
| 204 | +For security reasons, Maintainers should use 2FA for their accounts and |
| 205 | +if possible provide gpg signed commits. |
| 206 | +https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ |
| 207 | +https://help.github.com/articles/signing-commits-with-gpg/ |
| 208 | + |
| 209 | +## Owners |
| 210 | + |
| 211 | +Since Gitea is a pure community organization without any company support, |
| 212 | +to keep the development healthy we will elect three owners every year. All |
| 213 | +contributors may vote to elect up to three candidates, one of which will |
| 214 | +be the main owner, and the other two the assistant owners. When the new |
| 215 | +owners have been elected, the old owners will give up ownership to the |
| 216 | +newly elected owners. If an owner is unable to do so, the other owners |
| 217 | +will assist in ceding ownership to the newly elected owners. |
| 218 | +For security reasons, Owners or any account with write access (like a bot) |
| 219 | +must use 2FA. |
| 220 | +https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ |
| 221 | + |
| 222 | +After the election, the new owners should proactively agree |
| 223 | +with our [CONTRIBUTING](CONTRIBUTING.md) requirements in the |
| 224 | +[Discord](https://discord.gg/NsatcWJ) #general channel. Below are the |
| 225 | +words to speak: |
| 226 | + |
| 227 | +``` |
| 228 | +I'm honored to having been elected an owner of Gitea, I agree with |
| 229 | +[CONTRIBUTING](CONTRIBUTING.md). I will spend part of my time on Gitea |
| 230 | +and lead the development of Gitea. |
| 231 | +``` |
| 232 | + |
| 233 | +To honor the past owners, here's the history of the owners and the time |
| 234 | +they served: |
| 235 | + |
| 236 | +* 2016-11-04 ~ 2017-12-31 |
| 237 | + * [Lunny Xiao ](https://github.com/lunny) <[email protected]> |
| 238 | + * [Thomas Boerger ](https://github.com/tboerger) <[email protected]> |
| 239 | + * [Kim Carlbäcker ](https://github.com/bkcsoft) < [email protected]> |
| 240 | + |
| 241 | +* 2018-01-01 ~ 2018-12-31 |
| 242 | + * [Lunny Xiao ](https://github.com/lunny) <[email protected]> |
| 243 | + * [Lauris Bukšis-Haberkorns ](https://github.com/lafriks) <[email protected]> |
| 244 | + * [Kim Carlbäcker ](https://github.com/bkcsoft) < [email protected]> |
| 245 | + |
| 246 | +## Versions |
| 247 | + |
| 248 | +Gitea has the `master` branch as a tip branch and has version branches |
| 249 | +such as `release/v0.9`. `release/v0.9` is a release branch and we will |
| 250 | +tag `v0.9.0` for binary download. If `v0.9.0` has bugs, we will accept |
| 251 | +pull requests on the `release/v0.9` branch and publish a `v0.9.1` tag, |
| 252 | +after bringing the bug fix also to the master branch. |
| 253 | + |
| 254 | +Since the `master` branch is a tip version, if you wish to use Gitea |
| 255 | +in production, please download the latest release tag version. All the |
| 256 | +branches will be protected via GitHub, all the PRs to every branch must |
| 257 | +be reviewed by two maintainers and must pass the automatic tests. |
| 258 | + |
| 259 | +## Copyright |
| 260 | + |
| 261 | +Code that you contribute should use the standard copyright header: |
| 262 | + |
| 263 | +``` |
| 264 | +// Copyright 2018 The Gitea Authors. All rights reserved. |
| 265 | +// Use of this source code is governed by a MIT-style |
| 266 | +// license that can be found in the LICENSE file. |
| 267 | +``` |
| 268 | + |
| 269 | +Files in the repository contain copyright from the year they are added |
| 270 | +to the year they are last changed. If the copyright author is changed, |
| 271 | +just paste the header below the old one. |
0 commit comments