zzylol · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
@@ -0,0 +1,39 @@
+name: Bug report
+description: Something does not work as documented.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you saw, including error output.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: Commands, pipeline YAML or config, and input data. Keep it minimal.
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Commit
+      description: Output of `git rev-parse HEAD`.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, CPU, Rust version (`rustc --version`), and features used.
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/capability.yml b/.github/ISSUE_TEMPLATE/capability.yml
@@ -0,0 +1,46 @@
+name: New capability
+description: A new sketch function or use case.
+labels: ["capability"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        A capability answers one question about telemetry with a sketch.
+        See RFC 0001 (docs/rfcs/0001-sketch-telemetry-functions.md) for the existing use cases.
+  - type: textarea
+    id: question
+    attributes:
+      label: Question it answers
+      description: The question a user asks, in one or two sentences.
+      placeholder: Which attribute keys explode in cardinality?
+    validations:
+      required: true
+  - type: input
+    id: sketch
+    attributes:
+      label: Sketch
+      description: The asap_sketchlib sketch and what it is keyed by.
+      placeholder: HLL per (metric, attribute key)
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Output
+      description: The fields a user sees (keys, counts, quantiles, labels) and where they go (metrics, logs, ASAPQuery).
+    validations:
+      required: true
+  - type: textarea
+    id: bound
+    attributes:
+      label: Accuracy bound
+      description: The error bound reported next to each answer, and the sketch parameters it depends on.
+    validations:
+      required: true
+  - type: textarea
+    id: ground-truth
+    attributes:
+      label: Ground truth
+      description: The exact answer it is measured against, and how the workload makes that answer known.
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Long or cross-cutting design (RFC)
+    url: https://github.com/ProjectASAP/ASAPCollector-public/tree/main/docs/rfcs
+    about: Write an RFC in docs/rfcs instead of an issue. See docs/rfcs/README.md.
diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml
@@ -0,0 +1,36 @@
+name: Feature request
+description: A change to existing behavior, tooling or docs.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        For a new sketch function or use case, use the capability form.
+        For a long or cross-cutting design, write an RFC in docs/rfcs.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What is hard or impossible today.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: Describe it as before -> after.
+    validations:
+      required: true
+  - type: textarea
+    id: performance
+    attributes:
+      label: Expected performance impact
+      description: Effect on throughput, CPU, memory or latency, or "none".
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,28 @@
+## What changed
+
+<!-- Before -> after. One concern per PR. -->
+
+Before:
+
+After:
+
+## How verified
+
+<!-- Commands run, tests added, output checked. -->
+
+## Performance impact
+
+<!-- Measured numbers (throughput, CPU, memory, latency) with the command used, or "none". -->
+
+## Linked issue or RFC
+
+<!-- e.g. Fixes #123, RFC 0001 -->
+
+## Checklist
+
+Run in `asap-precompute-rs/`:
+
+- [ ] `cargo fmt --check`
+- [ ] `cargo clippy --all-targets --features otap-engine,stream-benchmark -- -D warnings`
+- [ ] `cargo test --features otap-engine,stream-benchmark`
+- [ ] This is one of at most two open PRs I have.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,108 @@
+# Contributing
+
+This guide is for people and for AI agents. Follow it as written. If a step
+does not fit your change, say so in the PR description.
+
+The project follows OpenTelemetry practice for roles, review and design
+documents.
+
+## Roles
+
+| Role | Who | What they do |
+| --- | --- | --- |
+| Contributor | Anyone | Opens issues and PRs, reviews any PR. |
+| Approver | Listed in [MAINTAINERS.md](MAINTAINERS.md) | Reviews PRs. An approver's approval counts toward merge. |
+| Maintainer | Listed in [MAINTAINERS.md](MAINTAINERS.md) | Merges PRs, cuts releases, accepts RFCs, sets project direction. |
+
+To become an approver:
+
+- Contributed for at least one month.
+- Authored several merged PRs that are not trivial.
+- Reviewed several PRs with useful comments.
+- Sponsored by one maintainer, with no objection from the others.
+
+To become a maintainer:
+
+- Has been an approver for at least two months.
+- Has reviewed a substantial share of PRs in that time.
+- Shows good judgement on design, performance and accuracy.
+- Sponsored by one maintainer and approved by a majority of maintainers.
+
+Changes to roles are made by a PR to `MAINTAINERS.md`. People who stop
+contributing move to the emeritus list.
+
+## Before you start
+
+- Bugs, small features and new capabilities: open an issue with the matching
+  form in `.github/ISSUE_TEMPLATE/`.
+- Long or cross-cutting designs: write an RFC in [docs/rfcs](docs/rfcs/README.md).
+- Discuss larger changes in an issue or in the weekly sync before writing code.
+
+## Pull requests
+
+- At most two open PRs per contributor. Finish or close one before opening a
+  third.
+- Keep PRs small and reviewable. One concern per PR. Split refactors from
+  behavior changes.
+- Fill in the PR template:
+  - What changed, written as before -> after.
+  - How you verified it: commands run, tests added, output checked.
+  - Performance impact: measured numbers when the change can affect
+    performance, otherwise "none".
+  - The linked issue or RFC.
+- Keep the PR up to date with `main` and answer review comments.
+- An approver or maintainer approves, and a maintainer merges.
+
+## Design principles
+
+1. **Performance is a feature.** Every change keeps the end-to-end benchmark
+   green. A change that can affect throughput, CPU, memory or latency reports
+   measured numbers.
+2. **Accuracy is stated as a bound next to every answer.** An estimate without
+   its error bound is not a finished feature.
+3. **Sketches use asap_sketchlib.** Use asap_sketchlib's implementations and the
+   ASAPv1 wire format only. Fix gaps in asap_sketchlib, not with a local copy.
+4. **Upstream-compatible with OTAP, no forks.** Nodes register through the
+   official OTAP Dataflow factories and depend on pinned upstream crates.
+
+## Local checks
+
+Run these in `asap-precompute-rs/` before you push. They must all pass.
+
+```sh
+cd asap-precompute-rs
+cargo fmt --check
+cargo clippy --all-targets --features otap-engine,stream-benchmark -- -D warnings
+cargo test --features otap-engine,stream-benchmark
+```
+
+## Benchmarks
+
+The benchmark is the evidence that a function is cheap enough to leave on.
+Three tiers run in CI:
+
+| Tier | When | Scope | Gate | Workflow |
+| --- | --- | --- | --- | --- |
+| Smoke | Every PR and every merge to `main` | fmt, clippy, tests, then `deploy/telemetry-functions/acceptance.py` on real collector containers | Fails on wrong answers | `ci.yml` |
+| Nightly sweep | Every day | Full rate sweep per scenario | Fails when throughput drops more than the margin (default 10%) against the previous night | `asap-sketch-benchmark.yml` |
+| PR comparison | A maintainer comments `/benchmark` on a PR | Reduced sweep, this PR vs `main` | Posts a comparison table | `benchmark-on-demand.yml` |
+
+Capacity numbers need dedicated CPUs: the nightly and on-demand tiers run on
+the runner named by the `BENCH_RUNNER` repository variable (see
+`benchmarks/README.md`). For a performance-related change, also paste the
+relevant numbers into the PR.
+
+## Weekly sync
+
+<!-- TODO(maintainers): add the meeting time, time zone and link. -->
+**Placeholder: time and link to be added by maintainers.**
+
+Anyone can join. Bring RFCs for review and PRs that are stuck.
+
+## Notes for AI agents
+
+- Follow every rule above, including the two-open-PR limit.
+- Run the local checks and paste their result into "How verified".
+- Do not invent benchmark numbers. Report only numbers you measured, with the
+  command that produced them.
+- Do not change accepted RFCs except as described in [docs/rfcs](docs/rfcs/README.md).
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
@@ -0,0 +1,12 @@
+# Maintainers and approvers
+
+See [CONTRIBUTING.md](CONTRIBUTING.md#roles) for what each role does and how
+to join.
+
+| Name | GitHub | Affiliation | Role |
+| --- | --- | --- | --- |
+| _To be filled in by the repository owner_ | | | Maintainer |
+
+## Emeritus
+
+None yet.
diff --git a/README.md b/README.md
@@ -77,6 +77,12 @@ and `resolve()` — the `sketch_type` dispatch table (factory + observer +
 `SketchType`). All of this sits on the host-neutral runtime in the same
 crate (`precompute`, `window`, `sketches/*`).
 
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for roles, PR rules, design
+principles and the local checks. Long or cross-cutting designs are written
+as RFCs in [`docs/rfcs/`](./docs/rfcs/README.md).
+
 ## Build & test
 
 For a continuous KLL vs exact comparison with every processor in its own