Skip to content

RU Contributing

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

Участие в разработке

Проект ориентирован на .NET 10, WinUI 3, Windows 10 build 19041+ и x64. 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

Архитектурные правила

  • platform-neutral logic → Shadowsocks.Core;
  • Windows API → Shadowsocks.Windows;
  • WinUI shell/tray → Shadowsocks.Windows.WinUI / Shadowsocks.WinUI;
  • не возвращать WinForms/WPF;
  • Shadowsocks.NetworkService остаётся изолированным elevated helper;
  • selectable traffic modes только User/Admin;
  • Game Mode остаётся автоматическим;
  • Local GeoSite/EasyList/ABP authority — только C# FilterEngine;
  • не возвращать abp.js, compiled-PAC backend или executable custom abp.txt.

Стиль C#

Следовать текущему .NET/Microsoft style:

  • PascalCase для public API;
  • camelCase для locals/parameters;
  • _camelCase для private instance fields;
  • ArgumentNullException.ThrowIfNull, ObjectDisposedException.ThrowIf и специализированные exception types;
  • culture-invariant форматирование для protocol/file/network data;
  • async APIs не блокировать через .Result/.Wait();
  • cancellation token прокидывать дальше, если операция поддерживает cancellation;
  • disposable ownership должен быть явным.

Не подавлять analyzer warning глобально, если можно исправить контракт. Узкое suppression допустимо только для документированного protocol requirement, например Shadowsocks EVP_BytesToKey MD5 compatibility.

JSON compatibility

Persisted модели могут менять C#-имя на Microsoft-style property только с сохранением старого JSON contract через JsonProperty, если это требуется для backward compatibility.

Изменение schema должно сопровождаться migration/regression tests.

Routing

Изменения FilterEngine должны сохранять:

  • exception priority;
  • user rules before generated defaults;
  • domain anchors/wildcards/options semantics;
  • last-known-good snapshot при невалидном rebuild;
  • parity между User Mode и Admin Host/SNI path.

Security-sensitive изменения

Особое ревью требуется для updater, WinDivert, DNSCrypt, plugin extraction/update, startup copy, named pipes, executable replacement и archive path traversal/Windows-ADS. Background plugin updates разрешены только для trusted built-in repository mappings; manual archives не auto-update. Произвольный repository updater нельзя добавлять без отдельного trust/asset-selection контракта.

Документация

Если меняется пользовательское поведение:

  • обновить EN/RU/ZH root README;
  • обновить соответствующие EN/RU/ZH Wiki pages;
  • обновить release notes/changelog при release-facing изменении;
  • обновить локализацию i18n.csv для любого user-visible текста.

Clone this wiki locally