-
Notifications
You must be signed in to change notification settings - Fork 112
开发指南
这个页面的主要内容为 PCL 社区版从配置开发环境到提交 PR 的全流程说明和一些注意事项。
Important
由于 PCL CE 面向的 .NET 8 Desktop 只支持 Windows 10 1607 或以上版本,故这个页面的所有内容都默认你使用足够新的 Windows 系统。如果你是 Linux / macOS 用户或使用旧版本的 Windows 系统,请自行配置虚拟机调试环境或升级系统,此处不再赘述。
对于 Linux / macOS 用户:.NET 8 支持跨平台交叉编译,因此你可以使用 Rider 开发并使用虚拟机环境来调试,具体过程请自行探索。
Tip
由于某些特殊因素,在中国内地对 GitHub 和 NuGet Gallery 的访问都不是很稳定,然而这是开发这个项目所必须的。如果你在内地,建议尽可能配置一个稳定的全局代理,否则可能会遇到千奇百怪的网络问题。
对于 NuGet Gallery ,你也可以选择用华为云提供的镜像,但由于众所周知的原因,你还是有可能因为限速策略导致压根没法下载 NuGet 包。
Note
如果你有充足的合作项目开发经验,可以跳过这一部分。
如果你之前没有读过这篇开发指南,且在开发项目时有过疑惑,如 "PCL.Core 这个项目为什么是空目录" "为什么直接 clone 下来会编译出错" "为什么社区总是要求我签名" "项目目前的结构是怎样的" 等问题,即便你自己解决了这个问题,也十分建议完整阅读一遍这篇指南,因为你的解决方法可能不是正确的、符合规范的。
任何没有 Git 多人合作项目经验的开发者,均有可能因为指南中提到的某个细节,而交上一些质量不佳的代码 (即所谓的 "石山代码")。甚至有经验者,若不了解项目结构,也可能会交上一些可维护性不足的代码。
因此,如果你没有足够的信心写出优质的提交和 PR,这篇指南将可能包含许多你不知道的需要注意的细节。同时后续如有查阅需求,也请善用侧边栏目录和文本搜索 (Ctrl + F) 功能。
作者虽参与过不少合作项目,但也难免有些知识盲区或是笔误,因此指南内容可能存在错误。如果你发现了错误,请于 Issue 或开发者交流群中指出,或是直接编辑本 Wiki 页面改正,不胜感谢。
此处列出最基础的环境需求信息供专业人士使用,如果你不了解它们,请直接阅读第二节。
版本控制工具: Git GPG 或 SSH
SDK 工具链: .NET SDK 9.0 或更高版本 .NET Desktop Runtime 8.0
* 此处 SDK 版本应等于或高于给出的版本;Runtime 版本为项目依赖的固定版本,即只能使用该版本,更高或更低均无法使用。
集成开发环境 (IDE): Visual Studio 2022 或更高版本 JetBrains Rider 2024年1月1日 或更高版本
* 十分建议同时安装 Visual Studio 和 Rider,因为 VS 对高版本框架新特性的支持有时甚至不如 Rider,如果你必须做出抉择且不知道该选什么,那就选 VS。
访问 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 签名,请自行配置。
若你的用户目录中存在 .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 子模块:
git clone https://github.com/PCL-Community/PCL2-CE
cd PCL2-CE
git submodule update --init --remoteNote
推荐 IDE 界面使用英文,因为查资料和交流更方便。此处引用 IDE 中的选项将会使用英文,若你使用中文,请自行对照翻译。
在仓库根目录中执行 dotnet build 以测试开发环境是否可用,并初始化项目文件结构和源生成器。
如果至此为止没有任何报错,那么恭喜你,开发环境已经没有问题,可以开始开发了。如果出现了报错,那么可能是开发环境不完整,请仔细阅读报错信息以定位问题。如果确定开发环境没有问题,仍然构建出错,那么可能是有人提交了 Breaking change 影响了构建,请等待代码更新,或到社区开发者 QQ 群中交流问题。
PCL 社区版基于 Visual Studio 解决方案 (slnx) 构建,整个仓库就是一个解决方案,其中包含四个项目 (未来可能还会有更多)。
启动器本体,包含了大多数程序逻辑。目前包括但不限于用户界面、Minecraft 相关管理工具、各种账户认证等许多可被用户感知到的功能性内容。
社区版核心库,包含了社区版的一些新逻辑和新功能实现。由于 Visual Basic 这个巨型石山无法享受 .NET 的很多新特性尤其是编译时特性,且其因语法极其复杂、流程控制不够清晰等缺点已不适合现代开发使用,故核心库引入较新的 C# 项目结构 (语言版本 12.0 + 编译时 null 检查),以期缓解 Visual Basic 几乎没有可维护性的现状。
项目引用是单向的,即只能在本体项目中引用核心库,无法反向引用。
核心库目前按照用途分出不同的目录和命名空间,各目录内包含的组件与其名称直接相关。若要添加新的内容,请尽可能不要创建新的一级目录 (除非这个内容完全不属于当前存在的任何分类),并尽量减少二级目录的使用。
核心库仓库与主仓库的关系: submodule
核心库的源生成器们。
一个用于检查核心库部分实现是否正确的测试项目,包含了一些对核心库中特定工具的测试,如果你写了新的工具,也可以向其中添加新的测试。
开发过程中请尽可能遵循技术规范。
若修改已经存在的文件,在符合规范的情况下应尽可能保留原来的代码风格,如缩进风格、空行、类成员放置的位置等;不符合规范可事先修改使其符合规范,并使用 style 类型提交修改后再开始编写自己的内容。
请尽一切可能避免 goto 语句和代码标签的使用,如果你认为某个功能只能使用 goto 实现,就请不要尝试实现它,最终成品 99.99% 情况下会变得几乎不可维护。 鉴于此类跳转结构巨大的维护难度,社区维护者很可能会直接拒绝使用 goto 语句的 PR。
Tip
给 Rider 用户的一些提示:
Rider 对 VB 的支持不是很好,如果无法适应可以使用 VS;但是 C# 这边 Rider 的开发体验就比 VS 好太多了,根本不是一个等级的。
若不更改主项目代码,可能会遇到 Core 项目的更改不生效的问题,在运行配置的前置任务中 "Build project" 前添加 "Clean solution" 即可解决。如果你用 VS 也遇到了这个问题,那没救,它不支持前置任务,你只能在每次编译之前手动 clean 一下主项目。
Warning
与任何业务逻辑有关系的代码均请在本地测试基本可用后再提交更改!除非你只是改了一些文本文件 (比如 README 等)。
实际上社区对于开发者提交的 bug 是很包容的,只要提交者肯修或者有人肯修都问题不大,但是请不要把完全不能跑的代码交上来,它们可能会被直接关闭...
具体提交/推送代码的方式各大 Git 管理工具都不完全一致,请自行探索和查看官方文档,这里不再赘述。
值得一提的是,如果你在前面的配置中跳过了签名配置的第三行命令 (使 Git 自动为所有提交签名),你可能需要每次提交都附带 -S 参数或设置你使用的 Git 管理工具以确保你的所有提交都附带签名,否则你的 PR 可能被拒绝合并。
Tip
尽可能在新分支而不是默认的 dev 分支提交,这样会避免很多合并时的冲突。
Warning
在向主仓库提交时,请不要把 PCL.Core 引用更新提交上来,它有概率会导致你的 PR 产生不可解决的冲突 (即解决掉冲突之后仍为有冲突状态),这是 GitHub 的设计缺陷,所以千!万!不!要!把!PCL.Core!引!用!更!新!提!交!上!来!
如果你需要更新 PCL.Core 子模块以使用最新提交中的功能,请单独更新 PCL.Core 仓库,现代 Git 管理应当支持这个功能,如果不支持或支持不良 (如 VS 的举世无敌垃圾 Git 管理),你可以 cd PCL.Core 然后 git pull 手动更新。
Warning
请在提交之前把所有更改检查一遍,确保这些更改都出自你自己,而不是由 IDE 或 IDE 插件等瞎几把改的。如果有很明显的非人为更改,相关 PR 可能会被直接关闭。
如果觉得自己的更改可能被判定成非人为更改,请在提交信息或 PR 描述中说明这个更改的用意。
当你的提交已经在 GitHub 仓库的某个新分支准备好后,便可以单击这里的 "New pull request" 按钮向社区版仓库发起 PR。左边选择目标分支,一般是 dev,右边选择你的更改分支。
Important
注意上游一定要选择社区版仓库!反人类的 GitHub 默认会选择官方版仓库,但是你确实应该是人类 (?),所以千万不要交错地方了!
接下来在下面的 PR 描述中写明你的 PR 都包含什么更改,以及,如果有的话,可能会造成什么问题、需要等待什么前置条件也一并写明。如果这个 PR 与某个 Issue 相关联,合并 PR 可以解决相关问题,请在 PR 描述中使用处理语句提及该 Issue,如 Close #270,GitHub 会自动将二者关联。
如果想让社区开发者更快看到你的 PR,请向 PCL-Community/CE-Project 请求 Review。