domi/forgejo-domi
1
0
Fork 0
forked from forgejo/forgejo
Code Pull requests Activity

Refactor docs (#13275)

Browse source 
* First pass

Signed-off-by: jolheiser <john.olheiser@gmail.com>

* More changes

Signed-off-by: jolheiser <john.olheiser@gmail.com>

* Redirects

Signed-off-by: jolheiser <john.olheiser@gmail.com>
This commit is contained in:
John Olheiser 2020-10-23 10:59:45 -05:00 • committed by GitHub
parent bfc553164a
commit 1d6b565de4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 132 additions and 226 deletions
Download patch file Download diff file Expand all files Collapse all files

319
docs/content/doc/developers/hacking-on-gitea.en-us.md Normal file
View file

@ -0,0 +1,319 @@
---
date: "2016-12-01T16:00:00+02:00"
title: "Hacking on Gitea"
slug: "hacking-on-gitea"
weight: 10
toc: false
draft: false
menu:
sidebar:
parent: "developers"
name: "Hacking on Gitea"
weight: 10
identifier: "hacking-on-gitea"
---
# Hacking on Gitea
## Installing go
You should [install go](https://golang.org/doc/install) and set up your go
environment correctly.
Next, [install Node.js with npm](https://nodejs.org/en/download/) which is
required to build the JavaScript and CSS files. The minimum supported Node.js
version is {{< min-node-version >}} and the latest LTS version is recommended.
**Note**: When executing make tasks that require external tools, like
`make misspell-check`, Gitea will automatically download and build these as
necessary. To be able to use these you must have the `"$GOPATH"/bin` directory
on the executable path. If you don't add the go bin directory to the
executable path you will have to manage this yourself.
**Note 2**: Go version {{< min-go-version >}} or higher is required; however, it is important
to note that our continuous integration will check that the formatting of the
source code is not changed by `gofmt` using `make fmt-check`. Unfortunately,
the results of `gofmt` can differ by the version of `go`. It is therefore
recommended to install the version of Go that our continuous integration is
running. As of last update, it should be Go version {{< go-version >}}.
## Installing Make
Gitea makes heavy use of Make to automate tasks and improve development. This
guide covers how to install Make.
#### On Linux
Install with the package manager.
On Ubuntu/Debian:
```bash
sudo apt-get install make
```
On Fedora/RHEL/CentOS:
```bash
sudo yum install make
```
#### On Windows
One of these three distributions of Make will run on Windows:
- [Single binary build](http://www.equation.com/servlet/equation.cmd?fa=make). Copy somewhere and add to `PATH`.
- [32-bits version](ftp://ftp.equation.com/make/32/make.exe)
- [64-bits version](ftp://ftp.equation.com/make/64/make.exe)
- [MinGW](http://www.mingw.org/) includes a build.
- The binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to `PATH`.
- [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make`
## Downloading and cloning the Gitea source code
The recommended method of obtaining the source code is by using `git clone`.
```bash
git clone https://github.com/go-gitea/gitea
```
(Since the advent of go modules, it is no longer necessary to build go projects
from within the `$GOPATH`, hence the `go get` approach is no longer recommended.)
## Forking Gitea
Download the master Gitea source code as above. Then, fork the
[Gitea repository](https://github.com/go-gitea/gitea) on GitHub,
and either switch the git remote origin for your fork or add your fork as another remote:
```bash
# Rename original Gitea origin to upstream
git remote rename origin upstream
git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git"
git fetch --all --prune
```
or:
```bash
# Add new remote for our fork
git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git"
git fetch --all --prune
```
To be able to create pull requests, the forked repository should be added as a remote
to the Gitea sources. Otherwise, changes can't be pushed.
## Building Gitea (Basic)
Take a look at our
<a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>instructions</a>
for <a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>building
from source</a>.
The simplest recommended way to build from source is:
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build
```
The `build` target will execute both `frontend` and `backend` sub-targets. If the `bindata` tag is present, the frontend files will be compiled into the binary. It is recommended to leave out the tag when doing frontend development so that changes will be reflected.
See `make help` for all available `make` targets. Also see [`.drone.yml`](https://github.com/go-gitea/gitea/blob/master/.drone.yml) to see how our continuous integration works.
## Building continuously
To run and continously rebuild when source files change:
````bash
make watch
````
On macOS, watching all backend source files may hit the default open files limit which can be increased via `ulimit -n 12288` for the current shell or in your shell startup file for all future shells.
### Formatting, code analysis and spell check
Our continuous integration will reject PRs that are not properly formatted, fail
code analysis or spell check.
You should format your code with `go fmt` using:
```bash
make fmt
```
and can test whether your changes would match the results with:
```bash
make fmt-check # which runs make fmt internally
```
**Note**: The results of `go fmt` are dependent on the version of `go` present.
You should run the same version of go that is on the continuous integration
server as mentioned above. `make fmt-check` will only check if your `go` would
format differently - this may be different from the CI server version.
You should run revive, vet and spell-check on the code with:
```bash
make revive vet misspell-check
```
### Working on JS and CSS
Either use the `watch-frontend` target mentioned above or just build once:
```bash
make build && ./gitea
```
Before committing, make sure the linters pass:
```bash
make lint-frontend
```
Note: When working on frontend code, set `USE_SERVICE_WORKER` to `false` in `app.ini` to prevent undesirable caching of frontend assets.
### Building and adding SVGs
SVG icons are built using the `make svg` target which compiles the icon sources defined in `build/generate-svg.js` into the output directory `public/img/svg`. Custom icons can be added in the `web_src/svg` directory.
### Building the Logo
The PNG versions of the logo are built from a single SVG source file `assets/logo.svg` using the `make generate-images` target. To run it, Node.js and npm must be available. The same process can also be used to generate a custom logo PNGs from a SVG source file. It's possible to remove parts of the SVG logo for the favicon build by adding a `detail-remove` class to the SVG nodes to be removed.
### Updating the API
When creating new API routes or modifying existing API routes, you **MUST**
update and/or create [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
documentation for these using [go-swagger](https://goswagger.io/) comments.
The structure of these comments is described in the [specification](https://goswagger.io/use/spec.html#annotation-syntax).
If you want more information about the Swagger structure, you can look at the
[Swagger 2.0 Documentation](https://swagger.io/docs/specification/2-0/basic-structure/)
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)
You should be careful not to break the API for downstream users which depend
on a stable API. In general, this means additions are acceptable, but deletions
or fundamental changes to the API will be rejected.
Once you have created or changed an API endpoint, please regenerate the Swagger
documentation using:
```bash
make generate-swagger
```
You should validate your generated Swagger file and spell-check it with:
```bash
make swagger-validate misspell-check
```
You should commit the changed swagger JSON file. The continous integration
server will check that this has been done using:
```bash
make swagger-check
```
**Note**: Please note you should use the Swagger 2.0 documentation, not the
OpenAPI 3 documentation.
### Creating new configuration options
When creating new configuration options, it is not enough to add them to the
`modules/setting` files. You should add information to `custom/conf/app.ini`
and to the
<a href='{{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}}'>configuration cheat sheet</a>
found in `docs/content/doc/advanced/config-cheat-sheet.en-us.md`
### Changing the logo
When changing the Gitea logo SVG, you will need to run and commit the results
of:
```bash
make generate-images
```
This will create the necessary Gitea favicon and others.
### Database Migrations
If you make breaking changes to any of the database persisted structs in the
`models/` directory, you will need to make a new migration. These can be found
in `models/migrations/`. You can ensure that your migrations work for the main
database types using:
```bash
make test-sqlite-migration # with sqlite switched for the appropriate database
```
## Testing
There are two types of test run by Gitea: Unit tests and Integration Tests.
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
```
Unit tests will not and cannot completely test Gitea alone. Therefore, we
have written integration tests; however, these are database dependent.
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
```
will run the integration tests in an sqlite environment. Integration tests
require `git lfs` to be installed. Other database tests are available but
may need adjustment to the local environment.
Look at
[`integrations/README.md`](https://github.com/go-gitea/gitea/blob/master/integrations/README.md)
for more information and how to run a single test.
Our continuous integration will test the code passes its unit tests and that
all supported databases will pass integration test in a Docker environment.
Migration from several recent versions of Gitea will also be tested.
Please submit your PR with additional tests and integration tests as
appropriate.
## Documentation for the website
Documentation for the website is found in `docs/`. If you change this you
can test your changes to ensure that they pass continuous integration using:
```bash
# from the docs directory within Gitea
make trans-copy clean build
```
You will require a copy of [Hugo](https://gohugo.io/) to run this task. Please
note: this may generate a number of untracked git objects, which will need to
be cleaned up.
## Visual Studio Code
A `launch.json` and `tasks.json` are provided within `contrib/ide/vscode` for
Visual Studio Code. Look at
[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/master/contrib/ide/README.md)
for more information.
## Submitting PRs
Once you're happy with your changes, push them up and open a pull request. It
is recommended that you allow Gitea Managers and Owners to modify your PR
branches as we will need to update it to master before merging and/or may be
able to help fix issues directly.
Any PR requires two approvals from the Gitea maintainers and needs to pass the
continous integration. Take a look at our
[`CONTRIBUTING.md`](https://github.com/go-gitea/gitea/blob/master/CONTRIBUTING.md)
document.
If you need more help pop on to [Discord](https://discord.gg/gitea) #Develop
and chat there.
That's it! You are ready to hack on Gitea.