跳至主要内容
版本：1.22.3

在 Gitea 上进行黑客攻击

快速入门​

要获得一个快速工作的开发环境，您可以使用 Gitpod。

Open in Gitpod

安装 Go​

您应该安装 Go 并正确设置您的 Go 环境。

接下来，使用 npm 安装 Node.js，这是构建 JavaScript 和 CSS 文件所需的。支持的最小 Node.js 版本为 18，建议使用最新的 LTS 版本。

注意

当执行需要外部工具的 make 任务（例如 make watch-backend）时，Gitea 会自动下载和构建这些工具（如有必要）。要使用这些工具，您必须将 "$GOPATH"/bin 目录添加到可执行路径中。如果您没有将 go bin 目录添加到可执行路径中，则需要自行管理。

注意

需要 Go 版本 1.22 或更高版本。Gitea 使用 gofmt 来格式化源代码。但是，gofmt 的结果可能会因 go 版本而异。因此，建议安装我们的持续集成正在运行的 Go 版本。截至上次更新，Go 版本应为 1.22。

要对模板文件进行 lint，请确保已安装Python 和Poetry。

安装 Make​

Gitea 大量使用 Make 来自动化任务并改进开发。本指南介绍如何安装 Make。

在 Linux 上​

使用包管理器安装。

在 Ubuntu/Debian 上

sudo apt-get install make

在 Fedora/RHEL/CentOS 上

sudo yum install make

在 Windows 上​

这三个 Make 发行版中的一个将在 Windows 上运行

  • 单个二进制文件构建。复制到某个地方并添加到 PATH 中。
  • MinGW-w64 / MSYS2。
    • MSYS2 是一个工具和库的集合，它为您提供了一个易于使用的环境来构建、安装和运行原生 Windows 软件，它包含 MinGW-w64。
    • 在 MingGW-w64 中，二进制文件被称为 mingw32-make.exe 而不是 make.exe。将 bin 文件夹添加到 PATH 中。
    • 在 MSYS2 中，您可以直接使用 make。请参阅MSYS2 移植。
    • 要使用 CGO_ENABLED 编译 Gitea（例如：SQLite3），您可能需要使用tdm-gcc 而不是 MSYS2 gcc，因为 MSYS2 gcc 头文件缺少一些仅限 Windows 的 CRT 函数，例如 _beginthread。
  • Chocolatey 包。运行 choco install make
注意

如果您尝试使用 Windows 命令提示符通过 make 进行构建，可能会遇到问题。建议使用上述提示（Git bash 或 MinGW），但是，如果您只有命令提示符（或可能是 PowerShell），您可以使用set 命令设置环境变量，例如 set TAGS=bindata。

下载和克隆 Gitea 源代码​

获取源代码的推荐方法是使用 git clone。

git clone https://github.com/go-gitea/gitea

（自从出现 Go 模块后，不再需要在 $GOPATH 内构建 Go 项目，因此不再推荐 go get 方法。）

分叉 Gitea​

如上所述，下载主要的 Gitea 源代码。然后，在 GitHub 上分叉Gitea 存储库，并切换 git 远程 origin 为您的分叉存储库，或者将您的分叉存储库添加为另一个远程存储库

# Rename original Gitea origin to upstream
git remote rename origin upstream
git remote add origin "[email protected]:$GITHUB_USERNAME/gitea.git"
git fetch --all --prune

或者

# Add new remote for our fork
git remote add "$FORK_NAME" "[email protected]:$GITHUB_USERNAME/gitea.git"
git fetch --all --prune

要能够创建拉取请求，分叉的存储库应该作为远程存储库添加到 Gitea 源代码中。否则，更改将无法推送。

构建 Gitea（基础）​

查看我们的说明，了解从源代码构建。

从源代码构建最简单且推荐的方式是

TAGS="bindata sqlite sqlite_unlock_notify" make build

build 目标将执行 frontend 和 backend 子目标。如果存在 bindata 标签，前端文件将被编译到二进制文件中。建议在进行前端开发时省略标签，以便更改能够反映出来。

查看 make help 以了解所有可用的 make 目标。还可以查看.drone.yml，了解我们的持续集成是如何工作的。

持续构建​

要运行并在源文件更改时持续重新构建

# for both frontend and backend
make watch

# or: watch frontend files (html/js/css) only
make watch-frontend

# or: watch backend files (go) only
make watch-backend

在 macOS 上，监视所有后端源文件可能会达到默认的打开文件限制，可以通过 ulimit -n 12288 为当前 shell 提高此限制，或者在您的 shell 启动文件中为所有未来的 shell 提高此限制。

格式化、代码分析和拼写检查​

我们的持续集成将拒绝未能通过代码 lint 的 PR（包括格式检查、代码分析和拼写检查）。

您应该格式化代码

make fmt

并对源代码进行 lint

# lint both frontend and backend code
make lint
# lint only backend code
make lint-backend

注意：gofmt 的结果取决于 go 版本。您应该运行与持续集成服务器上相同的 Go 版本（如上所述）。

处理 JS 和 CSS​

前端开发应遵循前端开发指南

要使用前端资源进行构建，可以使用上面提到的 watch-frontend 目标，或者只构建一次

make build && ./gitea

在提交之前，确保 lint 通过

make lint-frontend

配置本地 ElasticSearch 实例​

使用 docker 启动本地 ElasticSearch 实例

mkdir -p $(pwd)/data/elasticsearch
sudo chown -R 1000:1000 $(pwd)/data/elasticsearch
docker run --rm --memory="4g" -p 127.0.0.1:9200:9200 -p 127.0.0.1:9300:9300 -e "discovery.type=single-node" -v "$(pwd)/data/elasticsearch:/usr/share/elasticsearch/data" docker.elastic.co/elasticsearch/elasticsearch:7.16.3

配置 app.ini

[indexer]
ISSUE_INDEXER_TYPE = elasticsearch
ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
REPO_INDEXER_ENABLED = true
REPO_INDEXER_TYPE = elasticsearch
REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200

构建和添加 SVG​

SVG 图标是使用 make svg 目标构建的，该目标将图标源代码编译到输出目录 public/assets/img/svg 中。自定义图标可以添加到 web_src/svg 目录中。

Gitea Logo 的 PNG 和 SVG 版本是使用 TAGS="gitea" make generate-images 目标从单个 SVG 源文件 assets/logo.svg 构建的。要运行它，Node.js 和 npm 必须可用。

相同的方法也可以用于从 SVG 源文件生成自定义 Logo PNG，方法是更新 assets/logo.svg 并运行 make generate-images。省略 gitea 标签将只更新用户指定的 Logo 文件。

更新 API​

当创建新的 API 路由或修改现有的 API 路由时，您**必须**使用 Swagger 注释更新和/或创建这些路由的文档，方法是使用 go-swagger 注释。这些注释的结构在 规范 中有描述。如果您想了解更多关于 Swagger 结构的信息，您可以查看 Swagger 2.0 文档 或与之前添加新 API 端点的 PR 进行比较，例如 PR #5483

您应该注意不要破坏依赖稳定 API 的下游用户的 API。一般来说，这意味着添加是可以接受的，但删除或对 API 进行根本性更改将被拒绝。

创建或更改 API 端点后，请使用以下命令重新生成 Swagger 文档：

make generate-swagger

您应该验证生成的 Swagger 文件：

make swagger-validate

您应该提交更改后的 swagger JSON 文件。持续集成服务器将使用以下命令检查是否已完成此操作：

make swagger-check
注意

请注意，您应该使用 Swagger 2.0 文档，而不是 OpenAPI 3 文档。

创建新的配置选项​

创建新的配置选项时，仅仅将它们添加到 modules/setting 文件中是不够的。您应该在 custom/conf/app.ini 和 配置备忘单（位于 docs/content/doc/administer/config-cheat-sheet.en-us.md）中添加信息。

更改 Gitea 徽标 SVG 时，您需要运行并提交以下命令的结果：

make generate-images

这将创建必要的 Gitea 浏览器图标和其他文件。

数据库迁移​

如果您对 models/ 目录中任何持久化数据库结构进行破坏性更改，则需要进行新的迁移。这些迁移可以在 models/migrations/ 中找到。您可以使用以下命令确保您的迁移适用于主要数据库类型：

make test-sqlite-migration # with SQLite switched for the appropriate database

测试​

Gitea 运行两种类型的测试：单元测试和集成测试。

单元测试​

单元测试由 *_test.go 在 go test 系统中涵盖。您可以设置环境变量 GITEA_UNIT_TESTS_LOG_SQL=1 以在以详细模式运行测试时（即设置 GOTESTFLAGS=-v 时）显示所有 SQL 语句。

TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests

集成测试​

单元测试不会也不会单独完全测试 Gitea。因此，我们编写了集成测试；但是，这些测试依赖于数据库。

TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite

将在 SQLite 环境中运行集成测试。集成测试需要安装 git lfs。其他数据库测试可用，但可能需要调整本地环境。

查看 tests/integration/README.md 了解更多信息以及如何运行单个测试。

PR 测试​

我们的持续集成将测试代码通过其单元测试，并且所有支持的数据库都将在 Docker 环境中通过集成测试。还将测试从几个最近的 Gitea 版本迁移。

请根据需要提交包含附加测试和集成测试的 PR。

网站文档​

网站文档位于 docs/ 中。如果您更改了它，您可以使用以下命令测试更改以确保它们通过持续集成：

make lint-md

Visual Studio Code​

在 contrib/ide/vscode 中提供了用于 Visual Studio Code 的 launch.json 和 tasks.json。查看 contrib/ide/README.md 了解更多信息。

GoLand​

单击 /main.go 中 func main() 函数上的“运行应用程序”箭头可以快速启动可调试的 Gitea 实例。

在“运行/调试配置”中的“输出目录”**必须**设置为 gitea 项目目录（包含 main.go 和 go.mod），否则，已启动实例的工作目录将是 GoLand 的临时目录，并阻止 Gitea 在开发环境中加载动态资源（例如：模板）。

要在 GoLand 中使用 SQLite 运行单元测试，请在“运行/调试配置”的“Go 工具参数”中设置 -tags sqlite,sqlite_unlock_notify。

提交 PR​

对更改感到满意后，将其推送并打开一个拉取请求。建议您允许 Gitea 管理员和所有者修改您的 PR 分支，因为我们需要将其更新到主分支才能合并，或者可能能够直接帮助解决问题。

任何 PR 都需要两位 Gitea 维护者的批准，并且需要通过持续集成。查看我们的 CONTRIBUTING.md 文档。

如果您需要更多帮助，请加入 Discord #Develop 并进行聊天。

就是这样！您已准备好开始修改 Gitea。