Skip to content

Commit 3f7b816

Browse files
adelowoadelowo
committed
Merge remote-tracking branch 'origin/master' into lock_conversation
2 parents 09d5eb7 + 7a72aa6 commit 3f7b816

28 files changed

+1905
-754
lines changed

‎docs/content/doc/advanced/hacking-on-gitea.en-us.md

Lines changed: 260 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -15,41 +15,280 @@ menu:
1515

1616
# Hacking on Gitea
1717

18-
Familiarity with the existing [installation instructions](https://golang.org/doc/install)
19-
is required for this section.
18+
## Installing go and setting the GOPATH
2019

21-
To contribute to Gitea, fork the project and work on the `master` branch.
20+
You should [install go](https://golang.org/doc/install) and set up your go
21+
environment correctly. In particular, it is recommended to set the `$GOPATH`
22+
environment variable and to add the go bin directory or directories
23+
`${GOPATH//://bin:}/bin` to the `$PATH`. See the Go wiki entry for
24+
[GOPATH](https://github.com/golang/go/wiki/GOPATH).
2225

23-
Some internal packages are referenced using their respective Github URL. This can
24-
become problematic. To "trick" the Go tool into thinking this is a clone from the
25-
official repository, download the source code using "go get" and follow these instructions.
26+
You will also need make.
27+
<a href='{{< relref "doc/advanced/make.en-us.md" >}}'>(See here how to get Make)</a>
2628

27-
```
29+
**Note**: When executing make tasks that require external tools, like
30+
`make misspell-check`, Gitea will automatically download and build these as
31+
necessary. To be able to use these you must have the `"$GOPATH"/bin` directory
32+
on the executable path. If you don't add the go bin directory to the
33+
executable path you will have to manage this yourself.
34+
35+
**Note 2**: Go version 1.9 or higher is required, however it is important
36+
to note that our continuous integration will check that the formatting of the
37+
source code is not changed by `gofmt` using `make fmt-check`. Unfortunately,
38+
the results of `gofmt` can differ by the version of `go` it is therefore
39+
recommended to install the version of go that our continuous integration is
40+
running. At the time of writing this is Go version 1.11, however this can be
41+
checked by looking at the
42+
[master `.drone.yml`](https://github.com/go-gitea/gitea/blob/master/.drone.yml)
43+
(At the time of writing
44+
[line 67](https://github.com/go-gitea/gitea/blob/8917d66571a95f3da232a0c27bc1300210d10fde/.drone.yml#L67)
45+
is the relevant line - however this may change.)
46+
47+
## Downloading and cloning the Gitea source code
48+
49+
Go is quite opinionated about where it expects its source code, and simply
50+
cloning the Gitea repository to an arbitrary path is likely to lead to
51+
problems - the fixing of which is out of scope for this document. Further some
52+
internal packages are referenced using their respective Github URL and at
53+
present we use `vendor/` directories.
54+
55+
The recommended method of obtaining the source code is by using the `go get` command:
56+
57+
```bash
2858
go get -d code.gitea.io/gitea
59+
cd "$GOPATH/src/code.gitea.io/gitea"
2960
```
3061

31-
Fork the [Gitea repository](https://github.com/go-gitea/gitea) on GitHub, it should
32-
then be possible to switch the source directory on the command line.
62+
This will clone the Gitea source code to: `"$GOPATH/src/code.gitea.io/gitea"`, or if `$GOPATH`
63+
is not set `"$HOME/go/src/code.gitea.io/gitea"`.
3364

65+
## Forking Gitea
66+
67+
As stated above, you cannot clone Gitea to an arbitrary path. Download the master Gitea source
68+
code as above. Then fork the [Gitea repository](https://github.com/go-gitea/gitea) on GitHub,
69+
and either switch the git remote origin for your fork or add your fork as another remote:
70+
71+
```bash
72+
# Rename original Gitea origin to upstream
73+
cd "$GOPATH/src/code.gitea.io/gitea"
74+
git remote rename origin upstream
75+
git remote add origin "[email protected]:$GITHUB_USERNAME/gitea.git"
76+
git fetch --all --prune
3477
```
35-
cd $GOPATH/src/code.gitea.io/gitea
78+
79+
or:
80+
81+
```bash
82+
# Add new remote for our fork
83+
cd "$GOPATH/src/code.gitea.io/gitea"
84+
git remote add "$FORK_NAME" "[email protected]:$GITHUB_USERNAME/gitea.git"
85+
git fetch --all --prune
3686
```
3787

3888
To be able to create pull requests, the forked repository should be added as a remote
3989
to the Gitea sources, otherwise changes can't be pushed.
4090

91+
## Building Gitea (Basic)
92+
93+
Take a look at our
94+
<a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>instructions</a>
95+
for <a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>building
96+
from source</a>.
97+
98+
The simplest recommended way to build from source is:
99+
100+
```bash
101+
TAGS="bindata sqlite sqlite_unlock_notify" make generate build
41102
```
42-
git remote rename origin upstream
43-
git remote add origin [email protected]:<USERNAME>/gitea.git
44-
git fetch --all --prune
103+
104+
However, there are a number of additional make tasks you should be aware of.
105+
These are documented below but you can look at our
106+
[`Makefile`](https://github.com/go-gitea/gitea/blob/master/Makefile) for more,
107+
and look at our
108+
[`.drone.yml`](https://github.com/go-gitea/gitea/blob/master/.drone.yml) to see
109+
how our continuous integration works.
110+
111+
### Formatting, linting, vetting and spell-check
112+
113+
Our continous integration will reject PRs that are not properly formatted, fail
114+
linting, vet or spell-check.
115+
116+
You should format your code with `go fmt` using:
117+
118+
```bash
119+
make fmt
120+
```
121+
122+
and can test whether your changes would match the results with:
123+
124+
```bash
125+
make fmt-check # which runs make fmt internally
126+
```
127+
128+
**Note**: The results of `go fmt` are dependent on the version of `go` present.
129+
You should run the same version of go that is on the continuous integration
130+
server as mentioned above. `make fmt-check` will only check if your `go` would
131+
format differently - this may be different from the CI server version.
132+
133+
You should lint, vet and spell-check with:
134+
135+
```bash
136+
make vet lint misspell-check
137+
```
138+
139+
### Updating the stylesheets
140+
141+
At present we use [less](http://lesscss.org/) and [postcss](https://postcss.org) to generate our stylesheets. Do
142+
**not** edit the files in `public/css/` directly as they are generated from
143+
`lessc` from the files in `public/less/`.
144+
145+
If you wish to work on the stylesheets you will need to install `lessc` the
146+
less compiler and `postcss`. The recommended way to do this is using `npm install`:
147+
148+
```bash
149+
cd "$GOPATH/src/code.gitea.io/gitea"
150+
npm install
151+
```
152+
153+
You can then edit the less stylesheets and regenerate the stylesheets using:
154+
155+
```bash
156+
make generate-stylesheets
157+
```
158+
159+
You should commit both the changes to the css and the less files when making
160+
PRs.
161+
162+
### Updating the API
163+
164+
When creating new API routes or modifying existing API routes you **MUST**
165+
update and/or create [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
166+
documentation for these using [go-swagger](https://goswagger.io/) comments.
167+
The structure of these comments is described in the [specification](https://goswagger.io/use/spec.html#annotation-syntax).
168+
If you want more information about the Swagger structure you can look at the
169+
[Swagger 2.0 Documentation](https://swagger.io/docs/specification/2-0/basic-structure/)
170+
or compare with a previous PR adding a new API endpoint e.g. [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
171+
172+
You should be careful not to break the API for downstream users which depend
173+
on a stable API. In general this means additions are acceptable, but deletions
174+
or fundamental changes of API will be rejected.
175+
176+
Once you have created or changed an API endpoint, please regenerate the Swagger
177+
documentation using:
178+
179+
```bash
180+
make generate-swagger
181+
```
182+
183+
You should validate your generated Swagger file and spell-check it with:
184+
185+
```bash
186+
make swagger-validate mispell-check
187+
```
188+
189+
You should commit the changed swagger JSON file. The continous integration
190+
server will check that this has been done using:
191+
192+
```bash
193+
make swagger-check
194+
```
195+
196+
**Note**: Please note you should use the Swagger 2.0 documentation, not the
197+
OpenAPI 3 documentation.
198+
199+
### Creating new configuration options
200+
201+
When creating new configuration options, it is not enough to add them to the
202+
`modules/setting` files. You should add information to `custom/conf/app.ini`
203+
and to the
204+
<a href='{{ relref "doc/advanced/config-cheat-sheet.en-us.md"}}'>configuration cheat sheet</a>
205+
found in `docs/content/doc/advanced/config-cheat-sheet.en-us.md`
206+
207+
### Changing the logo
208+
209+
When changing the Gitea logo svg. You will need to run and commit the results
210+
of:
211+
212+
```bash
213+
make generate-images
214+
```
215+
216+
This will create the necessary Gitea favicon and others.
217+
218+
### Database Migrations
219+
220+
If you make breaking changes to any of the database persisted structs in the
221+
`models/` directory you will need to make a new migration. These can be found
222+
in `models/migrations/`. You can ensure that your migrations work for the main
223+
database types using:
224+
225+
```bash
226+
make test-sqlite-migration # with sqlite switched for the appropriate database
45227
```
46228

47-
This should provide a working development environment for Gitea. Take a look at
48-
the `Makefile` to get an overview about the available tasks. The most common tasks
49-
should be `make test` which will start our test environment and `make build` which
50-
will build a `gitea` binary into the working directory. Writing test cases is not
51-
mandatory to contribute, but it is highly encouraged and helps developers sleep
52-
at night.
229+
## Testing
230+
231+
There are two types of test run by Gitea: Unit tests and Integration Tests.
232+
233+
```bash
234+
TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
235+
```
236+
237+
Unit tests will not and cannot completely test Gitea alone. Therefore we
238+
have written integration tests, however, these are database dependent.
239+
240+
```bash
241+
TAGS="bindata sqlite sqlite_unlock_notify" make generate build test-sqlite
242+
```
243+
244+
Will run the integration tests in an sqlite environment. Other database tests
245+
are available however may need adjustment for local environment.
246+
247+
Look at
248+
[`integrations/README.md`](https://github.com/go-gitea/gitea/blob/master/integrations/README.md)
249+
for more information and how to run a single test.
250+
251+
Our continuous integration will test the code passes its unit tests and that
252+
all supported databases will pass integration test in a docker environment.
253+
Migration from several recent versions of gitea will also be tested.
254+
255+
Please submit your PR with additional tests and integration tests as
256+
appropriate.
257+
258+
## Documentation for the website
259+
260+
Documentation for the website is found in `docs/`. If you change this you
261+
can test your changes to ensure that they pass continuous integration using:
262+
263+
```bash
264+
cd "$GOPATH/src/code.gitea.io/gitea/docs"
265+
make trans-copy clean build
266+
```
267+
268+
You will require a copy of [Hugo](https://gohugo.io/) to run this task. Please
269+
note this may generate a number of untracked git objects which will need to
270+
be cleaned up.
271+
272+
## Visual Studio Code
273+
274+
A `launch.json` and `tasks.json` are provided within `contrib/ide/vscode` for
275+
Visual Studio Code. Look at
276+
[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/master/contrib/ide/README.md)
277+
for more information.
278+
279+
## Submitting PRs
280+
281+
Once you're happy with your changes, push them up and open a pull request. It
282+
is recommended that you allow Gitea Managers and Owners to modify your PR
283+
branches as we will need to update it to master before merging and/or may be
284+
able to help fix issues directly.
285+
286+
Any PR requires two approvals from the Gitea maintainers and needs to pass the
287+
continous integration. Take a look at our
288+
[`CONTRIBUTING.md`](https://github.com/go-gitea/gitea/blob/master/CONTRIBUTING.md)
289+
document.
290+
291+
If you need more help pop on to [Discord](https://discord.gg/gitea) #Develop
292+
and chat there.
53293

54-
That's it! You are ready to hack on Gitea. Test changes, push them to the repository,
55-
and open a pull request.
294+
That's it! You are ready to hack on Gitea.

0 commit comments

Comments
 (0)