10 KiB
| date | title | slug | weight | toc | draft | menu | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2016-12-01T16:00:00+02:00 | Hacking on Gitea | hacking-on-gitea | 10 | false | false |
|
Hacking on Gitea
Installing go and setting the GOPATH
You should install go and set up your go
environment correctly. In particular, it is recommended to set the $GOPATH
environment variable and to add the go bin directory or directories
${GOPATH//://bin:}/bin to the $PATH. See the Go wiki entry for
GOPATH.
You will also need make.
(See here how to get Make)
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 1.9 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. At the time of writing this is Go version 1.12; however, this can be
checked by looking at the
master .drone.yml
(At the time of writing
line 67
is the relevant line - but this may change.)
Downloading and cloning the Gitea source code
Go is quite opinionated about where it expects its source code, and simply
cloning the Gitea repository to an arbitrary path is likely to lead to
problems - the fixing of which is out of scope for this document. Further, some
internal packages are referenced using their respective GitHub URL and at
present we use vendor/ directories.
The recommended method of obtaining the source code is by using the go get command:
go get -d code.gitea.io/gitea
cd "$GOPATH/src/code.gitea.io/gitea"
This will clone the Gitea source code to: "$GOPATH/src/code.gitea.io/gitea", or if $GOPATH
is not set "$HOME/go/src/code.gitea.io/gitea".
Forking Gitea
As stated above, you cannot clone Gitea to an arbitrary path. Download the master Gitea source
code as above. Then, fork the Gitea repository on GitHub,
and either switch the git remote origin for your fork or add your fork as another remote:
# Rename original Gitea origin to upstream
cd "$GOPATH/src/code.gitea.io/gitea"
git remote rename origin upstream
git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git"
git fetch --all --prune
or:
# Add new remote for our fork
cd "$GOPATH/src/code.gitea.io/gitea"
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
instructions
for building
from source.
The simplest recommended way to build from source is:
TAGS="bindata sqlite sqlite_unlock_notify" make generate build
However, there are a number of additional make tasks you should be aware of.
These are documented below but you can look at our
Makefile for more,
and look at our
.drone.yml to see
how our continuous integration works.
Formatting, linting, vetting and spell-check
Our continous integration will reject PRs that are not properly formatted, fail
linting, vet or spell-check.
You should format your code with go fmt using:
make fmt
and can test whether your changes would match the results with:
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 lint, vet and spell-check with:
make vet lint misspell-check
Updating the stylesheets
To generate the stylsheets, you will need Node.js at version 8.0 or above.
At present we use less and postcss to generate our stylesheets. Do
not edit the files in public/css/ directly, as they are generated from
lessc from the files in public/less/.
If you wish to work on the stylesheets, you will need to install lessc the
less compiler and postcss. The recommended way to do this is using npm install:
cd "$GOPATH/src/code.gitea.io/gitea"
npm install
You can then edit the less stylesheets and regenerate the stylesheets using:
make generate-stylesheets
You should commit both the changes to the css and the less files when making
PRs.
Updating the API
When creating new API routes or modifying existing API routes, you MUST
update and/or create Swagger
documentation for these using go-swagger comments.
The structure of these comments is described in the specification.
If you want more information about the Swagger structure, you can look at the
Swagger 2.0 Documentation
or compare with a previous PR adding a new API endpoint, e.g. PR #5483
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:
make generate-swagger
You should validate your generated Swagger file and spell-check it with:
make swagger-validate mispell-check
You should commit the changed swagger JSON file. The continous integration
server will check that this has been done using:
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
configuration cheat sheet
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:
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:
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.
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.
TAGS="bindata sqlite sqlite_unlock_notify" make generate build test-sqlite
will run the integration tests in an sqlite environment. Other database tests
are available but may need adjustment to the local environment.
Look at
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:
cd "$GOPATH/src/code.gitea.io/gitea/docs"
make trans-copy clean build
You will require a copy of Hugo 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
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
document.
If you need more help pop on to Discord #Develop
and chat there.
That's it! You are ready to hack on Gitea.