Skip to content

Latest commit

 

History

History
325 lines (244 loc) · 13.4 KB

CONTRIBUTING.md

File metadata and controls

325 lines (244 loc) · 13.4 KB

Contributing to BotNexus

Thanks for wanting to poke the machine responsibly. BotNexus is an experimental C#/.NET platform for orchestrating LLM agents, tools, channels, and memory. This guide covers everything you need to build from source, make a change, and open a pull request that CI (and your fellow humans) will accept.

For a higher-level tour of the project, start with the README. For deeper topics, see the Documentation section below.


Prerequisites

Requirement Version Notes
.NET SDK 10.0.204 or later Pinned in global.json with rollForward: latestMinor. Earlier SDKs (including .NET 9) are not supported.
PowerShell 7+ (pwsh) Required for the repo helper and validation scripts under scripts/.
Git Recent Worktrees are used heavily (see Development Workflow).

Verify your SDK:

dotnet --version
# Must output 10.0.204 or later

Download the .NET 10 SDK: https://dotnet.microsoft.com/download/dotnet/10.0

BotNexus runs on Windows and Linux. All code, tests, scripts, and docs must be portable across both — CI runs on both and developer machines vary.


Getting Started (Dev Setup)

Clone the repo and restore tools and packages:

git clone https://github.com/sytone/botnexus.git
cd botnexus

dotnet tool restore   # installs pinned tools from dotnet-tools.json (dotnet-affected, etc.)
dotnet restore        # restores NuGet packages (Central Package Management)
dotnet build dirs.proj

Run the CLI directly from source:

dotnet run --project src/gateway/BotNexus.Cli -- init
dotnet run --project src/gateway/BotNexus.Cli -- provider setup
dotnet run --project src/gateway/BotNexus.Cli -- gateway start

Or run the gateway in the foreground:

dotnet run --project src/gateway/BotNexus.Cli -- serve

The WebUI and REST API serve at http://localhost:5005. For a fuller walkthrough see the Developer Setup guide.

Install the versioned git hooks (the #1602 core.bare guard runs on push; there is deliberately no pre-commit hook - see Validation):

pwsh scripts/repo/install-hooks.ps1

Development Workflow

Worktrees and Branches

All file modifications and commits happen in a dedicated worktree — never directly on main. Local main stays clean and aligned to origin/main.

# Create a worktree + branch off up-to-date main
git worktree add ../botnexus-wt/<issue-number>-<slug> -b <type>/<issue-number>-<slug>
cd ../botnexus-wt/<issue-number>-<slug>

Branch naming: <type>/<issue-number>-<short-slug> — for example fix/64-history-first-load or feat/128-gateway-plugins.

Ordinary PRs target main. For a planned change with at least two dependent, independently reviewable layers, GitHub native stacked PRs are permitted: the bottom branch targets main and each upper branch targets the branch below it. Do not stack unrelated work merely because it was developed at the same time. See PR and Commit Conventions.

Planning lives in GitHub Issues on sytone/botnexus (not in docs/planning/). Use gh issue list / gh issue view <number> to find work.

Conventional Commits

All commit messages use Conventional Commits:

<type>(<scope>): <short summary>
  • Types: feat, fix, refactor, docs, test, chore, ci, perf, build
  • Scope: the area affected — e.g. cli, gateway, scripts, domain, extensions, tools
  • Keep the summary lowercase, imperative mood, no trailing period
  • Commit in small logical batches — one feature, one fix, one refactor per commit
  • Multi-line bodies are encouraged for non-trivial changes: explain what and why, not how

Examples:

feat(cli): add serve command with gateway and probe subcommands
fix(gateway): prevent duplicate session writes on concurrent requests
refactor(scripts): simplify start-gateway.ps1 to delegate to CLI
docs(agents): add conventional commit rules for PRs
chore(deps): bump Microsoft.Extensions.* to 10.0.1

Pull Requests

  • PR titles must also follow Conventional Commits — GitHub uses the PR title as the squash-merge commit message, so a non-conforming title produces a non-conforming history entry.
  • Reference the issue number in the PR body (e.g. Closes #128), not the title.
  • When work is complete, close the issue with a comment referencing the PR or commit.

Writing Documentation

When writing or reviewing documentation, follow the shared Documentation standards. They define the three audiences, plain-language guidance, evidence requirements, and agent review boundaries. Use Documentation grooming for the existing checks and PR and commit conventions for the submission format. Apply the standard incrementally and respect document ownership headers.

Code Style

BotNexus enforces a few hard conventions. The full detail lives in AGENTS.md and the per-area AGENTS.md files under src/.

Full code standards - XML comment requirements, naming, dependency boundaries, and testing conventions - are in docs/development/code-standards.md.

  • Cross-platform paths. Production code injects IFileSystem (System.IO.Abstractions) and uses fileSystem.Path.Combine(...) rather than hardcoded separators or /tmp/. Use Path.Combine() in tests and static helpers. Never hardcode C:\... or /tmp/....
  • Value objects use Vogen. New identifiers are [ValueObject<T>] partial structs in BotNexus.Domain.Primitives with a Validate partial method. Do not add implicit operators — callers use .Value and .From(...) explicitly. See src/domain/AGENTS.md.
  • XML docs on public API. All public methods and properties need a <summary> explaining why the member exists and the context a caller needs — not a restatement of the signature.
  • Warnings are errors. Fix all compiler warnings during development; TreatWarningsAsErrors=true is enforced centrally. Do not silence warnings with #pragma warning disable, #nullable disable, or null-forgiving !.
  • No dead code, no [Obsolete]. This codebase has no external consumers — delete unused code and update call sites in the same commit instead of deprecating.

MSBuild conventions are centralized: TargetFramework, Nullable, and ImplicitUsings come from Directory.Build.props, and all package versions live in Directory.Packages.props (Central Package Management — no Version on individual PackageReferences).


Project Structure

botnexus/
├── src/
│   ├── agent/          agent core + provider adapters (Copilot, OpenAI, Anthropic, ...)
│   ├── domain/         BotNexus.Domain — domain model and Vogen value objects
│   ├── extensions/     channels (SignalR, Telegram, ServiceBus, TUI), tools, MCP, skills
│   ├── gateway/        gateway, CLI, cron, sessions, prompts, memory, tools, webhooks
│   └── persistence/    BotNexus.Persistence.Sqlite
├── tests/              unit, integration, architecture, scenario, component, e2e tests
├── docs/               published documentation site (MkDocs Material)
├── scripts/            build, test, repo, and local development scripts
├── examples/           experiments and sample integrations
└── tools/              supporting utilities

The root traversal project is dirs.proj. Many directories carry their own AGENTS.md with area-specific conventions — read the one closest to the code you are changing.


Running Tests

All tests must pass before a change is complete. Prefer Test-Driven Development: write the failing test first, then implement until it passes.

Run only the tests impacted by your change (plus the Architecture and Scenario safety-net suites):

scripts/repo/test-impacted.ps1

This uses dotnet-affected to select affected test projects and always adds the *.Architecture.Tests and *.Scenarios.Tests projects as a safety net. See Running Impacted Tests for parameters (-From, -Configuration, -All, -NoBuild, -DryRun) and the Windows testhost firewall pre-authorization details.

Architecture fitness functions live in tests/architecture/BotNexus.Architecture.Tests/ and structurally enforce the Vogen and scenario-suite conventions. Channel-agnostic acceptance tests live under tests/scenarios/ — read tests/scenarios/AGENTS.md before adding one. Every Blazor .razor component requires a corresponding bUnit component test.


Validation

The authoritative pre-push gate is:

scripts/repo/Invoke-PreCommitValidation.ps1

The canonical command was renamed from scripts/repo/Validate-PreCommit.ps1 to scripts/repo/Invoke-PreCommitValidation.ps1. This is a breaking path change: the old file is removed, with no alias or wrapper. Update external scripts and local skill references before invoking validation. This repository change does not migrate those external consumers. Parameters, mode selection, approval checks and exit behavior stay the same. The policy identity changes, so pre-migration receipts must not be reused. The paired offline fixtures are now Test-PreCommitValidation.ps1 and Test-AzureBuildTestArtifacts.ps1 under scripts/repo/.

Mode is selected via BOTNEXUS_VALIDATION_MODE (local or remote); the operational default is remote (#2158). Local validation spawns real gateway processes that outlive their parent and steal the live gateway's scheduled jobs, so it is opt-in and must not be run on a host with a live gateway. Select it explicitly only when remote infrastructure is genuinely unavailable:

$env:BOTNEXUS_VALIDATION_MODE = 'local'
scripts/repo/Invoke-PreCommitValidation.ps1

Install the versioned git hooks (the #1602 core.bare guard on push). There is deliberately no pre-commit hook - commit-time local validation is banned:

pwsh scripts/repo/install-hooks.ps1

Do not use --no-verify on commits containing code changes. A hand-run dotnet build is encouraged before validating - it costs seconds and starts no test host - but it is not itself the validation gate. Do not run dotnet test or test-impacted.ps1 on a host with a live gateway: the test host leaks gateway processes that outlive it (#2158). Test execution is remote.

Documentation-only changes skip the test gate. If your change touches nothing but *.md, docs/**, or mkdocs.yml, build the docs instead - it takes about twenty seconds and catches dead links:

npm ci          # first time only
npm run docs:build

This is what deploy-docs.yml runs. ci-build-test.yml already lists docs/** and **/*.md under paths-ignore, so a docs-only PR never triggers the test workflow. A change touching docs and code is a code change - validate it fully.


Debugging and Deeper Topics

The docs/development/ and docs/internals/ trees carry the in-depth material:

Topic Page
Agent execution model docs/development/agent-execution.md
Message flow docs/development/message-flow.md
Prompt pipeline docs/development/prompt-pipeline.md
LLM request lifecycle docs/development/llm-request-lifecycle.md
Gateway crash diagnostics docs/development/gateway-crash-diagnostics.md
WebUI connection issues docs/development/webui-connection.md
Session stores docs/development/session-stores.md
Workspace and memory docs/development/workspace-and-memory.md
DDD patterns docs/development/ddd-patterns.md
Agent core (internals) docs/internals/02-agent-core.md
Coding agent (internals) docs/internals/03-coding-agent.md
Tool development (internals) docs/internals/09-tool-development.md
Tool security (internals) docs/internals/tool-security.md

Documentation Map


Reporting Security Issues

Please review SECURITY.md for how to report vulnerabilities responsibly. Do not open a public issue for a security problem.


Welcome aboard. Build something interesting, keep main clean, and let the build warnings stay errors.