Skip to content

Commit eb72d7d

Browse files
Copilotpetesramek
Copilot
and
petesramek
authored
docs: add developer documentation under /docs (#155)
Adds a `/docs` folder with developer-focused guides covering the areas of the project that lack written explanation: composite actions, testing conventions, benchmarks, CI workflows, branching/versioning pipeline, API doc generation, and extensibility. ## New files - **`docs/README.md`** — index linking all sections - **`docs/local-development.md`** — build/test/format commands with correct config caveats (e.g. always use Release for tests) - **`docs/testing.md`** — project layout, MSTest conventions, data-driven tests, abstract-class testing pattern - **`docs/benchmarks.md`** — BenchmarkDotNet structure, writing benchmarks, full CLI flag reference, CI trigger variables - **`docs/composite-actions.md`** — catalogue of all 14 composite actions with inputs, outputs, usage context, and a template for adding new ones - **`docs/workflows.md`** — all 6 workflows with job-dependency tables, triggers, shared env vars, and a flow diagram showing how they chain - **`docs/branch-strategy.md`** — branch types, lifecycle diagram, protection rules, environment mapping - **`docs/versioning.md`** — branch naming → two-step `extract-version` / `format-version` pipeline with all output formulas and worked examples - **`docs/api-documentation.md`** — two DocFX manifests explained, publishing flow, how to add a new version to the site, local preview - **`docs/extensibility.md`** — how to subclass `AbstractPolylineEncoder` / `AbstractPolylineDecoder` for custom coordinate/polyline types, with examples drawn from existing benchmark code ## Updated - **`CONTRIBUTING.md`** — new *Developer Documentation* section with links to all `/docs` articles Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>
1 parent 6e0a0c7 commit eb72d7d

11 files changed

Lines changed: 1332 additions & 0 deletions

‎CONTRIBUTING.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,20 @@
22

33
Thank you for your interest in improving this library!
44

5+
## Developer Documentation
6+
7+
In-depth developer guides are in the [`/docs`](./docs/README.md) folder:
8+
9+
- [Local Development](./docs/local-development.md) — build, test, and format commands
10+
- [Testing](./docs/testing.md) — how to write unit tests
11+
- [Benchmarks](./docs/benchmarks.md) — how to write and run benchmarks
12+
- [Composite Actions](./docs/composite-actions.md) — reusable CI actions catalogue
13+
- [Workflows](./docs/workflows.md) — CI/CD pipeline overview
14+
- [Branch Strategy](./docs/branch-strategy.md) — branch lifecycle and environments
15+
- [Versioning](./docs/versioning.md) — branch naming and the version pipeline
16+
- [API Documentation](./docs/api-documentation.md) — DocFX and the API reference site
17+
- [Extensibility](./docs/extensibility.md) — how to add new encoding algorithms
18+
519
## Guidelines
620

721
- **Follow code style:** Use `.editorconfig` and run `dotnet format`.

‎docs/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Developer Documentation
2+
3+
Welcome to the developer documentation for **PolylineAlgorithm**. This section covers everything you need to contribute code, tests, benchmarks, and automation to the project.
4+
5+
## Contents
6+
7+
| Document | Description |
8+
|---|---|
9+
| [Local Development](./local-development.md) | Build, test, and format the codebase locally |
10+
| [Testing](./testing.md) | How to write and run unit tests |
11+
| [Benchmarks](./benchmarks.md) | How to write and run performance benchmarks |
12+
| [Composite Actions](./composite-actions.md) | Reusable GitHub Actions used across workflows |
13+
| [Workflows](./workflows.md) | CI/CD pipelines and how they connect |
14+
| [Branch Strategy](./branch-strategy.md) | Branch lifecycle and environment mapping |
15+
| [Versioning](./versioning.md) | Branch naming convention and the version pipeline |
16+
| [API Documentation](./api-documentation.md) | How DocFX generates and publishes the API reference site |
17+
| [Extensibility](./extensibility.md) | How to add new encoding algorithms |
18+
19+
## Quick Links
20+
21+
- [Contributing Guidelines](../CONTRIBUTING.md)
22+
- [API Reference Site](https://petesramek.github.io/polyline-algorithm-csharp/)
23+
- [GitHub Issues](https://github.com/petesramek/polyline-algorithm-csharp/issues)

‎docs/api-documentation.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# API Documentation
2+
3+
This document explains how API documentation is generated and published for PolylineAlgorithm.
4+
5+
## Toolchain
6+
7+
Documentation is built with [DocFX](https://dotnet.github.io/docfx/), a static site generator for .NET API references and Markdown guides.
8+
9+
## Repository Layout
10+
11+
```
12+
api-reference/
13+
├── api-reference.json # DocFX build manifest (site generation)
14+
├── assembly-metadata.json # DocFX metadata manifest (API extraction only)
15+
├── toc.yml # Top-level table of contents
16+
├── index.md # Landing page
17+
├── favicon.ico
18+
├── media/ # Images and other static assets
19+
├── guide/ # Markdown guide articles
20+
│ ├── toc.yml
21+
│ ├── introduction.md
22+
│ ├── getting-started.md
23+
│ ├── configuration.md
24+
│ ├── advanced-scenarios.md
25+
│ ├── sample.md
26+
│ └── faq.md
27+
├── 0.0/ # Auto-generated API metadata for version 0.0
28+
├── 1.0/ # Auto-generated API metadata for version 1.0
29+
│ └── *.yml # DocFX apiPage YAML files (one per type)
30+
└── _docs/ # Build output (excluded from DocFX content, gitignored)
31+
```
32+
33+
## Two DocFX Manifests
34+
35+
### `assembly-metadata.json` — API Extraction
36+
37+
Used by the `documentation/docfx-metadata` composite action during CI builds to extract XML documentation comments from source code and produce DocFX-compatible YAML files.
38+
39+
```json
40+
{
41+
"metadata": [{
42+
"src": [{ "src": "../src", "files": ["**/*.csproj"] }],
43+
"dest": "temp",
44+
"outputFormat": "apiPage"
45+
}]
46+
}
47+
```
48+
49+
- **Input:** All `.csproj` files under `src/`
50+
- **Output:** YAML files in `api-reference/temp/`, then copied to `api-reference/<version>/`
51+
- **When it runs:** Automatically after every successful `build` workflow run. The resulting YAML files are committed to the repository under `api-reference/<friendly-version>/` (e.g., `api-reference/1.2/`).
52+
53+
### `api-reference.json` — Site Build
54+
55+
Used by the `documentation/docfx-build` composite action to build the full documentation site.
56+
57+
```json
58+
{
59+
"build": {
60+
"content": [
61+
{ "files": ["index.md", "toc.yml", "guide/*.{md,yml}"], "exclude": ["_docs/**"] },
62+
{ "dest": "", "files": ["*.yml"], "group": "v1.0", "src": "1.0" },
63+
{ "dest": "", "files": ["*.yml"], "group": "v1.1", "src": "1.1" }
64+
],
65+
"output": "_docs",
66+
"template": ["default", "modern"]
67+
}
68+
}
69+
```
70+
71+
- **Input:** Markdown guide articles + versioned API YAML files
72+
- **Output:** Static HTML site in `api-reference/_docs/`
73+
- **When it runs:** During `release.yml` (automatic on every push to `preview/**` or `release/**`) and `publish-documentation.yml` (manual trigger).
74+
75+
## Publishing Flow
76+
77+
```
78+
src/ changed
79+
│
80+
▼
81+
[build.yml] → docfx metadata → commit YAML to api-reference/<version>/
82+
│
83+
▼
84+
[release.yml] or [publish-documentation.yml]
85+
│
86+
▼
87+
docfx build → api-reference/_docs/
88+
│
89+
▼
90+
GitHub Pages → petesramek.github.io/polyline-algorithm-csharp
91+
```
92+
93+
## Adding a New Version to the Site
94+
95+
When bumping the version to `X.Y`:
96+
97+
1. The `build` workflow automatically generates metadata YAML files into `api-reference/X.Y/` after the first build on the new branch.
98+
2. Add a new entry to `api-reference.json` under `build.content`:
99+
```json
100+
{ "dest": "", "files": ["*.yml"], "group": "vX.Y", "src": "X.Y", "rootTocPath": "~/toc.html" }
101+
```
102+
3. Add a matching group definition:
103+
```json
104+
"vX.Y": { "dest": "X.Y" }
105+
```
106+
4. Add the new version to `api-reference/toc.yml` so it appears in the navigation dropdown:
107+
```yaml
108+
- name: vX.Y
109+
href: X.Y/PolylineAlgorithm.html
110+
```
111+
112+
## Writing API Documentation
113+
114+
All public types, interfaces, and members must have XML doc comments. DocFX picks these up automatically:
115+
116+
```csharp
117+
/// <summary>
118+
/// Encodes a sequence of coordinates into a polyline string.
119+
/// </summary>
120+
/// <param name="coordinates">The coordinates to encode.</param>
121+
/// <returns>An encoded polyline string.</returns>
122+
public string Encode(IEnumerable<(double Latitude, double Longitude)> coordinates) { ... }
123+
```
124+
125+
After merging a change, verify the rendered documentation at the [API Reference Site](https://petesramek.github.io/polyline-algorithm-csharp/).
126+
127+
## Local Preview
128+
129+
To preview the documentation locally:
130+
131+
```bash
132+
dotnet tool update -g docfx
133+
docfx build ./api-reference/api-reference.json --serve
134+
```
135+
136+
Then open `http://localhost:8080` in your browser.

‎docs/benchmarks.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Benchmarks
2+
3+
This guide explains the benchmark project structure and how to write and run performance benchmarks.
4+
5+
## Project Structure
6+
7+
All benchmarks live in the `benchmarks/` directory:
8+
9+
```
10+
benchmarks/
11+
└── PolylineAlgorithm.Benchmarks/
12+
├── PolylineEncoderBenchmark.cs # Benchmarks for AbstractPolylineEncoder
13+
├── PolylineDecoderBenchmark.cs # Benchmarks for PolylineDecoder
14+
├── PolylineEncodingBenchmark.cs # Benchmarks for PolylineEncoding helpers
15+
├── Program.cs # BenchmarkSwitcher entry point
16+
└── PolylineAlgorithm.Benchmarks.csproj
17+
```
18+
19+
The project targets `net8.0`, `net9.0`, and `net10.0` and references the main `PolylineAlgorithm` library along with the `PolylineAlgorithm.Utility` helper project.
20+
21+
## Framework
22+
23+
Benchmarks use [BenchmarkDotNet](https://benchmarkdotnet.org/). Key packages:
24+
25+
| Package | Purpose |
26+
|---|---|
27+
| `BenchmarkDotNet` | Core benchmarking framework |
28+
| `BenchmarkDotNet.Diagnostics.Windows` | Windows-specific diagnostics (ETW) |
29+
30+
## Writing a New Benchmark
31+
32+
1. Create a new `.cs` file in `benchmarks/PolylineAlgorithm.Benchmarks/`.
33+
2. Add the standard copyright header.
34+
3. Annotate the class with `[MemoryDiagnoser]` if you want allocation tracking.
35+
4. Use `[Params]` to parameterize input sizes.
36+
5. Mark benchmark methods with `[Benchmark]`. Mark one with `[Benchmark(Baseline = true)]` when comparing variants.
37+
6. Use `[GlobalSetup]` to prepare shared data once per parameter combination.
38+
39+
Example:
40+
41+
```csharp
42+
//
43+
// Copyright © Pete Sramek. All rights reserved.
44+
// Licensed under the MIT License. See LICENSE file in the project root for full license information.
45+
//
46+
47+
namespace PolylineAlgorithm.Benchmarks;
48+
49+
using BenchmarkDotNet.Attributes;
50+
using BenchmarkDotNet.Engines;
51+
52+
/// <summary>
53+
/// Benchmarks for <see cref="MyEncoder"/>.
54+
/// </summary>
55+
[MemoryDiagnoser]
56+
public class MyEncoderBenchmark {
57+
private readonly Consumer _consumer = new();
58+
59+
[Params(1, 100, 1_000)]
60+
public int CoordinatesCount { get; set; }
61+
62+
private (double Latitude, double Longitude)[] _data = [];
63+
64+
[GlobalSetup]
65+
public void Setup() {
66+
_data = [.. RandomValueProvider.GetCoordinates(CoordinatesCount)];
67+
}
68+
69+
[Benchmark(Baseline = true)]
70+
public void EncodeArray() => new MyEncoder().Encode(_data).Consume(_consumer);
71+
}
72+
```
73+
74+
## Running Benchmarks Locally
75+
76+
Benchmarks **must** run in Release configuration to produce meaningful results:
77+
78+
```bash
79+
dotnet run \
80+
--project ./benchmarks/PolylineAlgorithm.Benchmarks/PolylineAlgorithm.Benchmarks.csproj \
81+
--configuration Release \
82+
--framework net10.0 \
83+
-- --filter '*'
84+
```
85+
86+
### Useful CLI flags
87+
88+
| Flag | Description |
89+
|---|---|
90+
| `--filter '*'` | Run all benchmarks |
91+
| `--filter '*Encoder*'` | Run benchmarks whose name contains `Encoder` |
92+
| `--runtimes net8.0 net9.0 net10.0` | Run on multiple runtimes |
93+
| `--exporters GitHub` | Export results as GitHub Flavored Markdown |
94+
| `--memory` | Enable memory diagnoser output |
95+
| `--iterationTime 100` | Iteration time in milliseconds |
96+
| `--join` | Merge results from multiple runs |
97+
| `--artifacts <path>` | Output directory for results |
98+
99+
### Example: multi-runtime run with GitHub export
100+
101+
```bash
102+
dotnet run \
103+
--project ./benchmarks/PolylineAlgorithm.Benchmarks/PolylineAlgorithm.Benchmarks.csproj \
104+
--configuration Release \
105+
--framework net10.0 \
106+
-- --runtimes net8.0 net9.0 net10.0 \
107+
--filter '*' \
108+
--exporters GitHub \
109+
--memory \
110+
--iterationTime 100 \
111+
--join \
112+
--artifacts /tmp/benchmarks
113+
```
114+
115+
## Benchmarks in CI
116+
117+
The `pull-request` workflow runs benchmarks on Ubuntu, Windows, and macOS when `vars.BENCHMARKDOTNET_RUN_OVERRIDE == 'true'` or when building a release branch. Results are uploaded as artifacts (`benchmark-<os>`) and written to the workflow step summary as a Markdown table.
118+
119+
Relevant workflow variables:
120+
121+
| Variable | Description |
122+
|---|---|
123+
| `BENCHMARKDOTNET_WORKING_DIRECTORY` | Working directory for `dotnet run` |
124+
| `BENCHMARKDOTNET_RUNTIMES` | Space-separated runtimes to bench |
125+
| `BENCHMARKDOTNET_FILTER` | Filter expression passed to `--filter` |
126+
| `DEFAULT_BUILD_FRAMEWORK` | Framework used with `--framework` |
127+
| `BENCHMARKDOTNET_RUN_OVERRIDE` | Set to `true` to force benchmark run on PRs |
128+
129+
## When to Add or Update Benchmarks
130+
131+
- Add a new benchmark file when introducing a new encoding/decoding code path.
132+
- Update an existing benchmark when changing the algorithmic implementation of an existing path.
133+
- Attach benchmark results to pull requests that affect performance-sensitive code (see [CONTRIBUTING.md](../CONTRIBUTING.md)).

0 commit comments

Comments
 (0)