# AGENTS – GeoVLog Contributors Guide

This document defines mandatory steps and best practices for anyone
modifying the repository. Read it before sending pull requests.

## 1. Workflow overview

1. **Clone** the repository and open `GeoVLog.sln` in Visual Studio 2022 or
   run `dotnet build` from the command line.
2. **Implement** your changes in the appropriate project under `src/` or
   tests under `tests/`.
3. **Before every commit** run the following commands from repository root:

   ```bash
   dotnet format
   dotnet test
   ```

   Both commands must succeed without errors or warnings. Fix any formatting
   or failing tests before committing.
4. **Commit** with a clear message prefixed by the subsystem tag:
   `[core]`, `[svc]`, `[reader]`, `[mon]`, or `[viewer]`.
5. **Open a Pull Request** targeting `main`. Include a short summary of the
   change, any relevant issue numbers, and the test results.

## 2. Repository layout

```
src/       Core library and application projects
    GeoVLog.Core/      – data models, crypto, HDF5 helpers
    GeoVLogSvc/        – Windows Service logger
    GeoVLogReader/     – CLI decrypt/extract tool
    GeoVLogMon/        – WPF monitor
    GeoVLogViewer/     – future analyst GUI

tests/     xUnit test projects
    GeoVLog.Tests/     – covers Core, service and reader

docs/      Sensor message specifications and other docs
```

Each project folder contains its own README describing build commands and
roadmap. Refer to them for project‑specific guidance.

## 3. Coding conventions

- **C# 11 / .NET 8** with `Nullable` reference types enabled.
- Treat compiler warnings as errors (`TreatWarningsAsErrors=true`).
- Structure code under `Models/`, `Crypto/`, `Hdf5/`, `Services/`,
  `ViewModels/` as appropriate.
- Avoid UI or host‑specific logic inside `GeoVLog.Core` – keep it
  platform‑agnostic.
- Keep public APIs immutable where possible and add unit tests for every
  public method.

- Use four spaces for indentation; no tabs.
- Keep line length under 120 characters.
- Public types and members should have XML documentation comments.
- Prefer `var` when the type is obvious; otherwise specify the type explicitly.
- Follow standard C# naming rules (PascalCase for types and methods, camelCase for locals and parameters).
- Structure code in a modular way to simplify updates and future expansion.
- Design code to be easily maintainable and updatable; provide detailed comments in English explaining complex logic.
- Use English names for all variables, methods, and classes.

## 4. Testing

The solution uses xUnit. Tests reside under `tests/` and are split by
category (`Core`, `Svc`, `Reader`). Use `dotnet test` to run them all. You
may filter by category, e.g.

```bash
dotnet test tests/GeoVLog.Tests --filter Category=Core
```

New features must include corresponding tests. All tests should pass before
submission.

## 5. Formatting and linting

Run `dotnet format` from the repository root prior to each commit. The
project enforces the default `.editorconfig` rules shipped with
`Microsoft.CodeAnalysis.NetAnalyzers`. No trailing whitespace or unused
using directives should remain.

## 6. Commit and PR guidelines

- Limit each commit to a focused change. Use descriptive commit messages such
  as `[svc] Add PPS GPIO handling`.
- Rebase onto `main` if your branch diverged.
- In the Pull Request description list:
  - The purpose of the change.
  - A summary of test results.
  - Any follow‑up work or TODOs.

## 7. Branch naming

Use short topic branches named `feature/<name>` or `fix/<name>`. Avoid long‑
running branches. Each branch should correspond to a PR.

## 8. Signed binaries

Production releases are Authenticode‑signed. When building official
packages, run the publish commands described in the root `README.md` and
sign the resulting executables. The service validates its own signature at
startup.

## 9. Support and contacts

For questions open an issue or contact `support@your-company.com`. Urgent
operations queries can be addressed to the ops hotline listed in the
service README.

---
_Last updated 2025-05-22_