贡献指南

相关源文件

• .circleci/config.yml
• .github/workflows/build-and-push-image.yml
• .github/workflows/golangci-lint.yml
• .github/workflows/goreleaser.yml
• .github/workflows/stale.yml
• .golangci.yml
• .goreleaser.yml
• README.md
• README_zh.md
• client/proxy/general_tcp.go
• doc/pic/sponsor_daytona.png
• doc/pic/sponsor_olares.jpeg
• dockerfiles/Dockerfile-for-frpc
• dockerfiles/Dockerfile-for-frps
• pkg/config/types/types.go
• pkg/util/util/util.go
• pkg/util/wait/backoff.go

本文档概述了为 frp 项目贡献的指南。它提供了关于开发工作流程、代码标准以及如何提交有效的拉取请求以帮助维护高质量代码的信息。

介绍

frp 是一个开源的快速反向代理，允许您将 NAT 或防火墙后面的本地服务器暴露给互联网。作为一个开源项目，frp 欢迎任何有兴趣改进该项目的人的贡献。本指南旨在帮助新贡献者了解如何有效地为 frp 做出贡献。

来源： README.md100-105 README_zh.md75-85

开发工作流

来源： README_zh.md75-85 .github/workflows/goreleaser.yml .github/workflows/golangci-lint.yml

快速入门

1. Fork the repository：首先，在 GitHub 上 fork frp 仓库 到您的账户。

2. Clone your fork：将您的 fork 克隆到本地机器以开始开发。

   git clone https://github.com/YOUR-USERNAME/frp.git
   cd frp
   

3. Add the upstream remote：这允许您同步您的 fork 与原始存储库。

   git remote add upstream https://github.com/fatedier/frp.git
   

4. Stay updated：定期将您的 fork 与上游存储库同步，尤其是在创建新分支之前。

   git fetch upstream
   git checkout dev
   git merge upstream/dev
   

来源： README_zh.md75-85 .github/workflows/goreleaser.yml .github/workflows/golangci-lint.yml

分支结构

frp 使用两个主要分支

• master：仅用于发布稳定版本
• dev：开发分支，所有贡献都应定向到此分支

贡献时，始终从 dev 分支创建您的功能分支，而不是 master 分支。

来源： README_zh.md82 .github/workflows/golangci-lint.yml3-7

拉取请求指南

对于 Bug 修复

1. Bug 修复可以直接作为拉取请求提交到 dev 分支。
2. 包含对 Bug 的清晰描述以及您的更改如何修复它。
3. 添加适当的测试用例以防止回归。

对于新功能

1. 首先创建一个 Issue：在实现新功能之前，创建一个描述性的 Issue

   • 该功能做什么
   • 为什么需要它
   • 一般实现方法

2. 等待批准：等待维护者讨论并批准该功能。

3. 实现：批准后，实现功能并提交一个引用该 Issue 的拉取请求。

来源： README_zh.md78-80

代码规范

来源： .github/workflows/golangci-lint.yml .circleci/config.yml .golangci.yml

代码风格

frp 使用 golangci-lint 进行代码 linting。配置可以在 .golangci.yml 中找到。启用的 linter 包括

• errcheck：检查未检查的错误
• gofumpt：更严格的 gofmt
• goimports：格式化导入
• revive：Go 的 Linter
• gosimple：简化代码
• govet：报告可疑的构造
• 以及 .golangci.yml 中配置的许多其他 linter。

您可以在提交 PR 之前在本地运行 linting。

golangci-lint run

来源： .golangci.yml12-37

测试

所有贡献都应包含适当的测试

1. 运行现有测试：确保您的更改不会破坏现有功能。

   make alltest
   

2. 添加新测试：对于新功能或 Bug 修复，请添加涵盖新代码的测试。

来源： .circleci/config.yml9-10

构建系统

frp 使用 Makefile 系统进行构建和测试。主要命令包括：

• make：构建 frpc 和 frps
• make frpc：仅构建客户端
• make frps：仅构建服务器
• make alltest：运行所有测试

对于交叉编译，项目使用自定义的 Makefile.cross-compiles 和 package.sh 脚本。

来源： dockerfiles/Dockerfile-for-frpc6 dockerfiles/Dockerfile-for-frps6 .github/workflows/goreleaser.yml20-22

文档贡献

强烈鼓励改进文档，尤其是英文文档。在贡献文档时

1. 确保技术准确性
2. 使用清晰、简洁的语言
3. 在适当的地方提供示例
4. 在适用时更新英文和中文文档

来源： README_zh.md81

报告问题

报告问题时

1. 使用 GitHub issue tracker
2. 提供关于您的环境的详细信息
3. 包含重现问题的步骤
4. 共享相关的日志或错误消息
5. 提及您正在使用的 frp 版本

使用 issues 可以帮助其他人找到类似问题的解决方案，并避免维护者反复回答相同的问题。

来源： README_zh.md77-78 README_zh.md85

项目结构

了解项目结构有助于贡献者更有效地浏览代码库。

来源： README.md33-47 client/proxy/general_tcp.go23-34

审查流程

frp 中的拉取请求会经历以下审查流程

1. Automated Checks：CI 运行测试和 linting
2. Code Review：维护者审查代码的质量和正确性
3. Revision：解决审查者提出的任何反馈
4. Approval：获得批准后，维护者将合并 PR

在审查过程中请保持耐心，因为维护者可能时间有限。使您的 PR 保持专注和简洁，以便更容易审查。

来源： .github/workflows/golangci-lint.yml .circleci/config.yml

通信

如有问题、建议或超出 GitHub issue 范围的合作，您可以通过 fatedier@gmail.com 联系维护者。

请记住，使用 GitHub Issues 来提问项目相关的问题，可以帮助其他人找到类似问题的解决方案，并避免维护者重复回答相同的问题。

来源： README_zh.md83-85

功能门控

当贡献实验性功能或可能存在破坏性更改的功能时，请使用特性门（feature gates）系统

特性门允许有条件地启用实验性功能。在添加新的特性门功能时，请遵循现有模式。

来源： README.md96-99

发布流程

frp遵循版本方案，其中：

• v0.x.x：当前开发版本
• v1.x.x：计划中的稳定版本（未来）
• v2.x.x：计划中的重大重新设计（未来，不向后兼容）

贡献时，请考虑您的更改适合哪个版本。

来源： README.md108-116

许可和版权

frp的所有贡献都必须根据Apache License 2.0进行许可，如文件头部所示。贡献代码时，请确保您的贡献符合此许可。

示例头部

来源： pkg/util/wait/backoff.go1-14 pkg/util/util/util.go1-14 client/proxy/general_tcp.go1-14

结论

为frp做出贡献是改进这个广泛用于网络隧道和反向代理功能的工具的一个好方法。通过遵循这些准则，您可以帮助维护项目的质量并确保贡献过程顺利。

感谢您对改进frp的兴趣！