Skip to content

ZH Contributing

Jump to bottom
SlimRG edited this page Aug 23, 2026 · 1 revision

参与开发

项目目标：.NET 10、WinUI 3、Windows 10 build 19041+、x64 only。Release SDK 通过 global.json 固定。

提交前验证

在 Windows 上执行：

.\packaging\Validate-Repository.ps1

dotnet restore .\shadowsocks-reborn.sln -p:Platform=x64 -r win-x64 -p:NuGetAudit=true -p:NuGetAuditMode=all
dotnet build .\shadowsocks-reborn.sln -c Release -p:Platform=x64 -m:1 --no-restore -p:TreatWarningsAsErrors=true
dotnet test .\Shadowsocks.UnitTests\Shadowsocks.UnitTests.csproj -c Release -p:Platform=x64 --no-build

涉及 packaging/storage/update 时还要执行：

.\packaging\Build-Release.ps1

架构规则

  • 平台无关逻辑放入 Shadowsocks.Core；
  • Windows API 放入 Shadowsocks.Windows；
  • WinUI shell/tray 放入 Shadowsocks.Windows.WinUI 或 Shadowsocks.WinUI；
  • 不重新引入 WinForms/WPF；
  • Shadowsocks.NetworkService 保持独立 elevated helper；
  • 用户可选 traffic mode 只有 User/Admin；
  • Game Mode 保持自动；
  • Local GeoSite/EasyList/ABP 的唯一 authority 是 C# FilterEngine；
  • 不恢复 abp.js、compiled-PAC backend 或 executable custom abp.txt。

C# 风格

遵循当前 .NET/Microsoft style：

  • public API 使用 PascalCase；
  • locals/parameters 使用 camelCase；
  • private instance field 使用 _camelCase；
  • 优先 ArgumentNullException.ThrowIfNull、ObjectDisposedException.ThrowIf 和具体 exception 类型；
  • protocol/file/network data 使用 invariant culture；
  • async code 不使用 .Result / .Wait() 阻塞；
  • API 支持 cancellation 时继续传递 token；
  • disposable ownership 必须明确。

不要为了消除 analyzer warning 使用全局 NoWarn。只有协议兼容性等有明确理由时才允许窄范围 suppression，例如 Shadowsocks EVP_BytesToKey 所需 MD5。

JSON 兼容性

持久化 model 的 C# 名称可以改为 Microsoft-style property，但必须通过 JsonProperty 保留旧 JSON contract。Schema 变化应配套 migration/regression tests。

Routing

修改 FilterEngine 时必须保持：

  • exception priority；
  • user rules 优先于 generated defaults；
  • domain anchor/wildcard/options 语义；
  • rebuild 失败时保留 last-known-good snapshot；
  • User Mode 与 Admin Host/SNI path 行为一致。

安全敏感改动

Updater、WinDivert、DNSCrypt、plugin extraction/update、startup copy、named pipes、EXE replacement、archive traversal/Windows-ADS 需要额外 review。Background plugin update 仅允许 trusted built-in repository mapping；manual archive 不 auto-update。没有独立 trust/asset-selection contract 时不得加入任意 repository updater。

文档与本地化

用户可见行为变化时：

  • 同步 EN/RU/ZH root README；
  • 同步对应 EN/RU/ZH Wiki；
  • 更新 release notes/changelog；
  • 新增 UI text 时更新 i18n.csv 所有支持语言。

Clone this wiki locally