Skip to content

docs(agents): point at canonical framework conventions, drop dup ecosystem section #152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ANcpLua merged 1 commit into from
May 13, 2026
Merged

docs(agents): point at canonical framework conventions, drop dup ecosystem section #152

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 8 additions & 58 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,14 @@
# AGENTS.md — ANcpLua.NET.Sdk

Opinionated MSBuild SDK providing standardized defaults, policy enforcement, and analyzer injection for .NET projects. `CLAUDE.md` symlinks here.
## Framework conventions

Branch protection, auto-merge, CodeRabbit posture, release flow, dependency
graph, and the cross-repo bootstrap rules for the four ANcpLua framework
repos are documented in one place at
[ANcpLua/renovate-config](https://github.com/ANcpLua/renovate-config#ancplua-framework-conventions--renovate-config).
This file documents conventions specific to this repo only.


## SDK Variants

Expand Down Expand Up @@ -249,61 +257,3 @@ agents in v3.3.0 — see `src/*.nuspec` for the enumerated pattern as of v3.3.1)
workflow file or docs, `has_changes` goes false by design — touch a file under
one of the watched paths to force a publish.

## ANcpLua Ecosystem

| Repo | Purpose | NuGet | CI checks required |
|---|---|---|---|
| [ANcpLua.NET.Sdk](https://github.com/ANcpLua/ANcpLua.NET.Sdk) | Opinionated MSBuild SDK — standardized defaults, policy enforcement, analyzer injection | [nuget.org](https://www.nuget.org/packages/ANcpLua.NET.Sdk) | `compute_version`, `lint_config`, `test (ubuntu/windows/macos)`, `create_nuget` |
| [ANcpLua.Analyzers](https://github.com/ANcpLua/ANcpLua.Analyzers) | Custom Roslyn analyzers (auto-injected by the SDK) | [nuget.org](https://www.nuget.org/packages/ANcpLua.Analyzers) | `build`, `test (ubuntu/windows/macos)` |
| [ANcpLua.Roslyn.Utilities](https://github.com/ANcpLua/ANcpLua.Roslyn.Utilities) | Source generator utilities, TryParse extensions, polyfills | [nuget.org](https://www.nuget.org/packages/ANcpLua.Roslyn.Utilities) | `build (ubuntu/windows)`, `version` |
| [ANcpLua.Agents](https://github.com/ANcpLua/ANcpLua.Agents) | MAF runtime helpers + agent test infrastructure | [nuget.org](https://www.nuget.org/packages/ANcpLua.Agents) | `build (ubuntu/windows/macos)`, `version` |

### Branch protection (all 4 repos)

- PR required to merge into `main` (0 approvals, squash preferred)
- Required status checks must pass (CI jobs listed above)
- Branch must be up-to-date with `main` before merge
- Force push and branch deletion blocked on `main`
- Optional checks (CodeRabbit, GitGuardian, Copilot review, auto-merge) do not block merges

### Dependency graph

```
ANcpLua.NET.Sdk
├── injects ANcpLua.Analyzers (compile-time)
└── ships Version.props (version truth for all consumers)

ANcpLua.Analyzers
└── consumes ANcpLua.Roslyn.Utilities.Sources (source-only, internal)

ANcpLua.Roslyn.Utilities
└── standalone (no first-party deps)

ANcpLua.Agents
└── standalone (no first-party deps)
```

### Release flow

The four repos use two different patterns. Don't assume what works in one applies to the others.

**This repo (ANcpLua.NET.Sdk) — auto-bump-on-merge:**

1. PR to `main` — CI runs, auto-merge bots handle dep bumps
2. On merge, the `publish` workflow:
- `compute_version` reads the latest `v*` tag and bumps the patch (`v3.4.14` → `3.4.15`); reuses the tag's version when HEAD is exactly the tag
- `Must Publish Packages` gate fires only if `*.nuspec`, `src/**/*`, or `tests/**/*` changed (docs-only PRs skip deploy)
- `deploy` job pushes packages to NuGet via trusted publishing, then `gh release create v$VERSION` creates the GitHub release **and the tag** in one step
3. NuGet indexes in ~4-8 minutes — downstream repos pick up via Renovate

To force a minor/major bump instead of auto-patch, push the tag manually before the workflow runs (compute_version honors the tag if HEAD points at it).

**ANcpLua.Roslyn.Utilities, ANcpLua.Agents — manual-tag-triggers-publish:**

1. PR to `main` — CI runs (build + test only on push, no publish; `publish` job gated by `is_release=true`)
2. After merge, push a tag manually: `git tag vX.Y.Z && git push --tags`
3. Tag push triggers the workflow's release path: version comes from `${GITHUB_REF_NAME#v}`, packages publish, `gh release create` creates the GitHub release

**ANcpLua.Analyzers — manual-tag-publish-only:**

Same as Roslyn.Utilities/Agents on the trigger side (workflow runs only on `push: tags v*` or `workflow_dispatch`), but the workflow does **not** call `gh release create` — only the NuGet push. The tag itself is the release marker; if you want a GitHub release entry, create it manually after.
Loading