-
Notifications
You must be signed in to change notification settings - Fork 111
开发指南
Warning
PCL-CE 仓库内 Wiki 已被迁移至 docs.pclc.cc,此处所记载的内容可能过时。也请不要再对此 Wiki 进行维护。
这个页面的主要内容为 PCL 社区版从配置开发环境到提交 PR 的全流程说明和一些注意事项。
Important
由于 PCL CE 面向的 .NET 8 Desktop 只支持 Windows 10 1607 或以上版本,故这个页面的所有内容都默认你使用足够新的 Windows 系统。如果你是 Linux / macOS 用户或使用旧版本的 Windows 系统,请自行配置虚拟机调试环境或升级系统,此处不再赘述。
对于 Linux / macOS 用户:.NET 支持跨平台交叉编译,因此你可以使用 Rider 开发并使用虚拟机环境来调试,具体过程请自行探索。
Tip
由于某些特殊因素,在中国内地对 GitHub 和 NuGet Gallery 的访问都不是很稳定,然而这是开发这个项目所必须的。如果你在内地,建议尽可能配置一个稳定的全局代理,否则可能会遇到千奇百怪的网络问题。
对于 NuGet Gallery ,你也可以选择用华为云提供的镜像,但由于众所周知的原因,你还是有可能因为限速策略导致压根没法下载 NuGet 包。
任何没有 Git 多人合作项目经验的开发者,均有可能因为指南中提到的某个细节,而交上一些质量不佳的代码 (即所谓的 "石山代码")。甚至有经验者,若不了解项目结构,也可能会交上一些可维护性不足的代码。
因此,如果你没有足够的信心写出优质的提交和 PR,这篇指南将可能包含许多你不知道的需要注意的细节。同时后续如有查阅需求,也请善用侧边栏目录和文本搜索 (Ctrl + F) 功能。
此处列出最基础的环境需求信息供专业人士使用,如果你不了解它们,请直接阅读第二节。
版本控制工具: Git GPG 或 SSH
SDK 工具链: .NET SDK 10.0 或更高版本 .NET Desktop Runtime 8.0
* 此处 SDK 版本应等于或高于给出的版本;Runtime 版本为项目依赖的固定版本,即只能使用该版本,更高或更低均无法使用。
集成开发环境 (IDE): JetBrains Rider 2025年3月2日 或更高版本 Visual Studio 2026 或更高版本
Tip
我们建议所有开发者若无特殊需求尽可能使用 Rider 而不是 VS 来开发,VS 总是会有各种奇奇怪怪的问题,且时常会在未经允许的情况下擅自对代码进行大量格式/排版更改。
若由于特殊原因必须使用 VS,请务必在提交前再三审查,以确保不会将 VS 的无意义更改(包括但不限于缩进、空格等代码风格改动,BOM 头等编码结构改动)提交上来。
访问 Git 官网 选择 "Download for Windows" 获取安装包并运行,如果你不知道那些选项是做什么的,保持默认无脑下一步即可。如果需要的话,你也可以使用 winget install git 来安装 Git 工具,但是它会直接使用默认配置,且可能不会安装 Git 凭据管理器。若无特殊需求,建议尽可能从官网下载安装包来安装。
使用命令配置 Git 基本信息:
git config --global user.email 你的邮箱 git config --global user.name 你的名字
Note
名字请尽可能与 GitHub 用户名一致,当然如果就是想用别的也不是不可以...这个页面的主要作者就从来都不用 GitHub 用户名。
邮箱必须与 GitHub 账户使用的邮箱一致用于认证身份。请尽可能避免使用内地的邮箱服务,如网易 163 / 126 / QQ 邮箱 / Foxmail / 钉钉等,这会导致你的身份信息更容易泄露并产生一些人身安全问题。
Tip
如果你的提交被 GitHub 拒绝,请检查这个页面最底部的 "Block command line pushes that expose my email" 是否已取消勾选。
请避免使用 GitHub 的 Web Editor 来提交代码,它可能会产生各种问题。如有需求,请使用 GitHub 提供的 VSCode 网页版,记得将链接中的 PCL-Community 替换为你自己的用户名。
点击这个链接下载 Visual Studio 安装工具。
Tip
如果你不打算装 VS 也可以点击这个链接下载不包含 IDE 的安装工具。
下载后运行安装包,会提示正在配置 Visual Studio Installer,等待它配置完毕。
配置结束后会自动启动 Visual Studio 安装器,在 "可用" 中选择 Community 版本的 "安装",打开负载选择页面。
选择 ".NET 桌面开发",单击右下角的 "安装" ,等待安装结束即可。
Note
社区版仓库要求 PR 中的所有提交必须附带已验证的签名,因此需要配置本地提交签名,并将相关的公钥内容添加到 GitHub 账户用于验证。这里介绍配置相对更简单的 SSH 签名,如果你想用看起来更酷的 GPG 签名,请自行配置。
若使用 GPG 签名,请确保提交使用的邮箱与签名的邮箱一致
若你的用户目录中存在 .ssh 目录且其中存在 id_rsa id_ed25519 等类似的文件,则可以直接使用。若没有,使用以下命令生成 SSH 密钥对:
ssh-keygen -t ed25519 -C "你的邮箱"
会依次提示输入保存位置、密码和重复输入密码,默认直接 Enter 即可。如果你想要为密钥设置密码,直接输入内容并 Enter 即可,默认情况下不会显示输入的密码内容。
使用以下命令配置 Git 使用 SSH 签名:
git config --global gpg.format ssh git config --global user.signingkey "公钥文件位置" git config --global commit.gpgsign true
如果你不需要让 Git 在每次提交时都自动签名,请跳过第三行。
这里的公钥文件位置在 Windows 上一般使用绝对路径以保证不出问题,即 C:\Users\用户名\.ssh\公钥名.pub。
Tip
可以在你的 .ssh 目录中按住 Shift 右击公钥文件选择 "复制文件路径" 快速得到公钥文件的绝对路径。
Warning
请一定使用扩展名为 .pub 的公钥文件,而不是没有扩展名的密钥文件。
请务必再次确保此节中设置的邮箱与 GitHub 账户中通过验证的任意邮箱一致,否则你的提交将会变为 "Unverified"!
在这个页面选择右上角的 "New SSH key","Title" 输入一个你觉得合适的名字,"Key type" 选择 "Signing Key","Key" 填入刚刚的公钥文件内容 (可以右键公钥文件选择 "编辑" 查看内容),然后单击 "Add SSK key" 将这个公钥添加到账户中。
Important
如果你是社区成员,直接 Clone 本仓库即可;如果你是外部开发者,请 Fork 本仓库到自己的个人或组织账户中,并 Clone 自己账户中的 Fork 版本以方便提交 PR。
在你专门用来放项目代码的目录 (如果没有的话,新建一个,比如 C:\Projects) 运行以下命令 Clone 仓库到本地:
git clone https://github.com/PCL-Community/PCL-CE
Note
推荐 IDE 界面使用英文,因为查资料和交流更方便。此处引用 IDE 中的选项将会使用英文,若你使用中文,请自行对照翻译。
在仓库根目录中执行 dotnet build 以测试开发环境是否可用,并初始化项目文件结构和源生成器。
如果至此为止没有任何报错,那么恭喜你,开发环境已经没有问题,可以开始开发了。如果出现了报错,那么可能是开发环境不完整,请仔细阅读报错信息以定位问题。如果确定开发环境没有问题,仍然构建出错,那么可能是有人提交了 Breaking change 影响了构建,请等待代码更新,或到社区开发者 QQ 群中交流问题。
PCL 社区版基于 Visual Studio 解决方案 (slnx) 构建,整个仓库就是一个解决方案,其中包含四个项目 (未来可能还会有更多)。
启动器本体,包含了大多数程序逻辑。目前包括但不限于用户界面、Minecraft 相关管理工具、各种账户认证等许多可被用户感知到的功能性内容。
社区版核心库,包含了社区版的一些新逻辑和新功能实现。
项目引用是单向的,即只能在本体项目中引用核心库,无法反向引用。
核心库目前按照用途分出不同的目录和命名空间,各目录内包含的组件与其名称直接相关。若要添加新的内容,请尽可能不要创建新的一级目录 (除非这个内容完全不属于当前存在的任何分类),并尽量减少二级目录的使用。
小知识: 曾经 PCL.Core 是通过 submodule 集成进主仓库的。
核心库的源生成器们。
一个用于检查核心库部分实现是否正确的测试项目,包含了一些对核心库中特定工具的测试,如果你写了新的工具,也可以向其中添加新的测试。
开发过程中请尽可能遵循技术规范。
若修改已经存在的文件,在符合规范的情况下应尽可能保留原来的代码风格,如缩进风格、空行、类成员放置的位置等;不符合规范可事先修改使其符合规范,并使用 style 类型提交修改后再开始编写自己的内容。
请尽一切可能避免 goto 语句和代码标签的使用,如果你认为某个功能只能使用 goto 实现,就请不要尝试实现它,最终成品 99.99% 情况下会变得几乎不可维护。 鉴于此类跳转结构巨大的维护难度,社区维护者很可能会直接拒绝使用 goto 语句的 PR。
我们欢迎贡献者合理使用 AI 工具(例如 GitHub Copilot、ChatGPT、DeepSeek、Claude 等)来提升开发效率。为了确保代码质量和代码可维护性,请在使用人工智能工具的同时遵守以下规则。
Warning
提交的 PR 不符合以下要求可能会被维护者关闭,多次提交不符合要求的 PR 维护者有权禁止您在仓库的进一步活动。
提交者必须明确注明使用人工智能。通过在提交消息末尾或者 PR 标题末尾添加诸如 [DeepSeek-V3.2]、[Claude-Opus-4.6] 等标识,来明确说明生成此段代码使用的模型以及其版本。
示例标题/提交信息:
fix(any-scope): something is fixed caused by what [GPT-5.1]
大型 PR 在此处的判定
一次性新增或修改代码行数超过 200 行
一次性修改超过 5 个
.cs或者.xaml。
在此类 PR 中,不允许将 AI 生成的代码未经拆分、理解和重构就直接提交。请将大型任务拆解为小步提交(Small Commits),并确保每一处逻辑变更都是你完全理解且能解释清楚的。否则,维护者极有可能拒绝并关闭您的 PR。
AI 生成的代码(无论使用的模型多先进)往往会存在代码质量问题,提交者必须对提交的代码负责,人工审查并修正代码缺陷。维护者无义务协助审查 AI 生成的代码。
- 检查代码风格: 代码风格是否符合技术规范中要求。
- 检查逻辑缺陷:是否存在
TODO注释未处理;是否存在虚假 API 参数;是否存在重复造轮子;是否存在性能问题。 - 检查冗余度是否合理:设计是否过度;是否引入了不必要的依赖。
Warning
与任何业务逻辑有关系的代码均请在本地测试基本可用后再提交更改!除非你只是改了一些文本文件 (比如 README 等)。
具体提交/推送代码的方式各大 Git 管理工具都不完全一致,请自行探索和查看官方文档,这里不再赘述。
值得一提的是,如果你在前面的配置中跳过了签名配置的第三行命令 (使 Git 自动为所有提交签名),你可能需要每次提交都附带 -S 参数或设置你使用的 Git 管理工具以确保你的所有提交都附带签名,否则你的 PR 可能由于缺少签名被拒绝合并。
Tip
尽可能在新分支而不是默认的 dev 分支提交,这样会避免很多合并时的冲突。
Warning
请在提交之前把所有更改检查一遍,确保这些更改都出自你自己,而不是由 IDE 或 IDE 插件等自动工具改的。如果有大量很明显的非人为更改或与主题无关的更改,相关 PR 可能会被关闭。
如果觉得自己的更改可能被判定成非人为更改,请在提交信息或 PR 描述中说明这个更改的用意。
当你的提交已经在 GitHub 仓库的某个新分支准备好后,便可以单击这里的 "New pull request" 按钮向社区版仓库发起 PR。左边选择目标分支,一般是 dev,右边选择你的更改分支。
接下来在下面的 PR 描述中写明你的 PR 都包含什么更改,以及,如果有的话,可能会造成什么问题、需要等待什么前置条件也一并写明。如果这个 PR 与某个 Issue 相关联,合并 PR 可以解决相关问题,请在 PR 描述中使用处理语句提及该 Issue,如 Close #270,GitHub 会自动将二者关联。
在 PR 合并前,若要同步上游更改,请勿使用 rebase 和 squash merge,而是直接使用最普通的 merge 来同步。
如果想让社区开发者更快看到你的 PR,请向 PCL-Community/CE-Dev 请求 Review。
提交 PR 之后,你需要等待社区开发者 (即 PCL-Community/CE-Dev Team) 审核,并解决审核过程中提出的问题。
在解决问题之后,请不要点击 Resolve 按钮(除非你十分确信这个问题被解决了),这会给开发者后续审核造成不便。若有任何解释或后续问题,请直接在开发者提出的问题下方回复。