Merge pull request #120 from GeWuYou/feat/docs-add-repository-guide

docs(guide): 添加仓库开发指南文档
docs(guide): 更新提交和拉取请求指南中的拼写错误
2026-03-22 10:34:30 +08:00 · 2026-03-20 08:36:02 +08:00 · 2026-03-20 08:24:17 +08:00 · 2026-03-20 08:18:00 +08:00 · 2026-03-20 08:12:51 +08:00 · 2026-03-20 08:12:35 +08:00
8 changed files with 49 additions and 6 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,42 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`GFramework.sln` is the entry point for the full .NET solution. Runtime code lives in `GFramework.Core/`,
+`GFramework.Game/`, `GFramework.Godot/`, and `GFramework.Ecs.Arch/`. Interface-only contracts stay in the paired
+`*.Abstractions/` projects. Roslyn generators are split across `GFramework.SourceGenerators/`,
+`GFramework.Godot.SourceGenerators/`, and `GFramework.SourceGenerators.Common/`. Tests mirror the runtime modules in
+`GFramework.Core.Tests/`, `GFramework.Game.Tests/`, `GFramework.Ecs.Arch.Tests/`, and
+`GFramework.SourceGenerators.Tests/`. Documentation is under `docs/`, Godot templates under `Godot/script_templates/`,
+and repository utilities under `scripts/` and `refactor-scripts/`.
+
+## Build, Test, and Development Commands
+
+- `dotnet build GFramework.sln` builds the full solution from the repo root.
+- `dotnet test GFramework.sln --no-build` runs all NUnit test projects after a build.
+- `dotnet test GFramework.Core.Tests --filter "FullyQualifiedName~CommandExecutorTests.Execute"` runs a focused NUnit
+  test.
+- `bash scripts/validate-csharp-naming.sh` checks PascalCase namespace and directory rules used by CI.
+- `cd docs && bun install && bun run dev` starts the VitePress docs site locally.
+
+## Coding Style & Naming Conventions
+
+Use standard C# formatting with 4-space indentation and one public type per file. The repository keeps `ImplicitUsings`
+disabled and `Nullable` enabled, so write explicit `using` directives and annotate nullability carefully. Follow
+`PascalCase` for types, methods, namespaces, directories, and constants; use `_camelCase` for private fields and
+`camelCase` for locals and parameters. Keep namespaces aligned with folders, for example
+`GFramework.Core.Architectures`.
+
+## Testing Guidelines
+
+Tests use NUnit 4 with `Microsoft.NET.Test.Sdk`; some suites also use Moq. Place tests in the matching module test
+project and name files `*Tests.cs`. Prefer directory parity with production code, for example `GFramework.Core/Logging/`
+and `GFramework.Core.Tests/Logging/`. Add or update tests for every behavior change, especially public APIs, source
+generators, and integration paths.
+
+## Commit & Pull Request Guidelines
+
+Recent history follows Conventional Commits style such as `feat(events): ...`, `refactor(localization): ...`,
+`docs(guide): ...`, and `test(localization): ...`. Keep commits scoped and imperative. PRs should explain the
+motivation, implementation, and validation commands run; link related issues; and include screenshots when docs, UI, or
+Godot-facing behavior changes.
--- a/GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj
+++ b/GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj
@ -17,7 +17,7 @@
        <Using Include="GFramework.Core.Abstractions"/>
    </ItemGroup>
    <ItemGroup>
-        <PackageReference Update="Meziantou.Analyzer" Version="3.0.19">
+        <PackageReference Update="Meziantou.Analyzer" Version="3.0.25">
            <PrivateAssets>all</PrivateAssets>
            <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
        </PackageReference>
--- a/GFramework.Core.Tests/GFramework.Core.Tests.csproj
+++ b/GFramework.Core.Tests/GFramework.Core.Tests.csproj
@ -21,6 +21,7 @@
    </ItemGroup>

    <ItemGroup>
+      <PackageReference Include="Scriban" Version="6.6.0" />
        <ProjectReference Include="..\GFramework.Core\GFramework.Core.csproj"/>
        <ProjectReference Include="..\GFramework.SourceGenerators.Abstractions\GFramework.SourceGenerators.Abstractions.csproj"/>
        <ProjectReference Include="..\GFramework.SourceGenerators.Common\GFramework.SourceGenerators.Common.csproj"/>
--- a/GFramework.Core/GFramework.Core.csproj
+++ b/GFramework.Core/GFramework.Core.csproj
@ -11,7 +11,7 @@
        <ProjectReference Include="..\$(AssemblyName).Abstractions\$(AssemblyName).Abstractions.csproj"/>
    </ItemGroup>
    <ItemGroup>
-        <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.4"/>
+        <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.5"/>
        <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" Version="8.0.0"/>
    </ItemGroup>
 </Project>
--- a/GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj
+++ b/GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj
@ -19,7 +19,7 @@
        <Using Include="GFramework.Game.Abstractions"/>
    </ItemGroup>
    <ItemGroup>
-        <PackageReference Update="Meziantou.Analyzer" Version="3.0.19">
+        <PackageReference Update="Meziantou.Analyzer" Version="3.0.25">
            <PrivateAssets>all</PrivateAssets>
            <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
        </PackageReference>
--- a/GFramework.Godot.SourceGenerators.Abstractions/GFramework.Godot.SourceGenerators.Abstractions.csproj
+++ b/GFramework.Godot.SourceGenerators.Abstractions/GFramework.Godot.SourceGenerators.Abstractions.csproj
@ -19,7 +19,7 @@
        <Folder Include="logging\"/>
    </ItemGroup>
    <ItemGroup>
-        <PackageReference Update="Meziantou.Analyzer" Version="3.0.19">
+        <PackageReference Update="Meziantou.Analyzer" Version="3.0.25">
            <PrivateAssets>all</PrivateAssets>
            <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
        </PackageReference>
--- a/GFramework.SourceGenerators.Abstractions/GFramework.SourceGenerators.Abstractions.csproj
+++ b/GFramework.SourceGenerators.Abstractions/GFramework.SourceGenerators.Abstractions.csproj
@ -18,7 +18,7 @@
        <ProjectReference Include="..\GFramework.Core.Abstractions\GFramework.Core.Abstractions.csproj" PrivateAssets="all"/>
    </ItemGroup>
    <ItemGroup>
-        <PackageReference Update="Meziantou.Analyzer" Version="3.0.19">
+        <PackageReference Update="Meziantou.Analyzer" Version="3.0.25">
            <PrivateAssets>all</PrivateAssets>
            <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
        </PackageReference>
--- a/GFramework.SourceGenerators.Common/GFramework.SourceGenerators.Common.csproj
+++ b/GFramework.SourceGenerators.Common/GFramework.SourceGenerators.Common.csproj
@ -22,7 +22,7 @@
            <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
        </PackageReference>
        <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" PrivateAssets="all"/>
-        <PackageReference Update="Meziantou.Analyzer" Version="3.0.19">
+        <PackageReference Update="Meziantou.Analyzer" Version="3.0.25">
            <PrivateAssets>all</PrivateAssets>
            <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
        </PackageReference>
Author	SHA1	Message	Date
gewuyou	dfae4ba207	Merge pull request #120 from GeWuYou/feat/docs-add-repository-guide docs(guide): 添加仓库开发指南文档	2026-03-20 08:36:02 +08:00
GeWuYou	ccb51791a3	docs(guide): 更新提交和拉取请求指南中的拼写错误 - 修复了 "Conventional Commit" 到 "Conventional Commits" 的拼写 - 确保文档中使用的术语与业界标准保持一致	2026-03-20 08:24:17 +08:00
GeWuYou	55234c4d70	docs(guide): 添加仓库开发指南文档 - 创建了项目结构和模块组织说明 - 添加了构建测试和开发命令指南 - 定义了代码风格和命名约定规范 - 提供了测试指南和最佳实践 - 包含了提交和拉取请求准则 - 记录了解决方案文件和目录布局说明	2026-03-20 08:18:00 +08:00
dependabot[bot]	108bcbf27e	Bump Meziantou.Analyzer from 3.0.19 to 3.0.25 --- updated-dependencies: - dependency-name: Meziantou.Analyzer dependency-version: 3.0.25 dependency-type: direct:production update-type: version-update:semver-patch - dependency-name: Meziantou.Analyzer dependency-version: 3.0.25 dependency-type: direct:production update-type: version-update:semver-patch - dependency-name: Meziantou.Analyzer dependency-version: 3.0.25 dependency-type: direct:production update-type: version-update:semver-patch - dependency-name: Meziantou.Analyzer dependency-version: 3.0.25 dependency-type: direct:production update-type: version-update:semver-patch - dependency-name: Meziantou.Analyzer dependency-version: 3.0.25 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com>	2026-03-20 08:12:51 +08:00
dependabot[bot]	51393c30ee	Bump Microsoft.Extensions.DependencyInjection from 10.0.4 to 10.0.5 --- updated-dependencies: - dependency-name: Microsoft.Extensions.DependencyInjection dependency-version: 10.0.5 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com>	2026-03-20 08:12:35 +08:00
dependabot[bot]	589f9f7d63	Bump the nuget group with 1 update Bumps Scriban from 6.2.0 to 6.6.0 --- updated-dependencies: - dependency-name: Scriban dependency-version: 6.6.0 dependency-type: direct:production dependency-group: nuget ... Signed-off-by: dependabot[bot] <support@github.com>	2026-03-20 08:12:18 +08:00