Skip to content

docs: README rewrite + community files (LICENSE, CONTRIBUTING, CoC, SECURITY)#15

Merged
dpsoft merged 5 commits into
mainfrom
chore/readme-and-community
May 3, 2026
Merged

docs: README rewrite + community files (LICENSE, CONTRIBUTING, CoC, SECURITY)#15
dpsoft merged 5 commits into
mainfrom
chore/readme-and-community

Conversation

@dpsoft
Copy link
Copy Markdown
Owner

@dpsoft dpsoft commented May 3, 2026

GitHub's community profile flagged this repo for missing the four standard files (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY). At the same time, the README hit a new reader with an 80-line ASCII architecture diagram in slot 2 — before they'd seen a single command. This PR fixes both, plus a small .gitignore patch for stray local files.

What's in here

1. Community files (commit e9c23855)

  • LICENSE — canonical Apache 2.0 text from apache.org.
  • CONTRIBUTING.md — build/test/PR conventions, redirects to BUILDING.md, states in-scope vs. out-of-scope (no cluster-wide watchers, no telemetry — keeps feature triage consistent with the project's stated philosophy).
  • CODE_OF_CONDUCT.md — Contributor Covenant 2.1, reporting contact set to maintainer email + GitHub Security Advisories.
  • SECURITY.md — vuln reporting path (Security Advisory preferred, email fallback), explicit threat model and scope. Calls out that the agent runs with CAP_SYS_ADMIN/CAP_BPF/CAP_PERFMON/CAP_SYS_PTRACE/CAP_CHECKPOINT_RESTORE, so privilege-escalation and kernel-DoS reports are taken seriously.

2. .gitignore patch (commit 826259ec)

Stray files that keep showing up in git status:

  • isolate-*-v8.log (Node.js V8 logs from JS workload runs)
  • pmu.txt (stray PMU capture)
  • .codex (Anthropic CLI cache)
  • test/workloads/go/{cpu_bound,io_bound} (built binaries; sources stay tracked)

3. README rewrite (commit 28ecd33f)

New top-of-file:

  • One-line italic tagline distinct from the prose intro.
  • Badge row: CI, Tests, Go reference, Go version, license.
  • Auto-style table of contents.
  • --- separators between H2s (visual hierarchy).

New sections:

  • Quickstart — 3 commands (build, setcap, capture). First content section.
  • What it does — single table with all four modes (on-CPU, off-CPU, PMU, library).
  • vs the alternatives — concrete row-by-row comparison against perf record / parca-agent / pyroscope-ebpf / py-spy. Helps people pick the right tool, which is more honest than vague positioning.
  • Profiling inside a Kubernetes pod — short subsection mentioning the namespace-aware --pid + pprof k8s labels we just shipped (feat(perfagent): namespace-aware --pid + k8s pprof labels #14), with links rather than re-explaining.

The architecture deep-dive ASCII diagram and procmap.Resolver narrative are preserved verbatim — just moved below user-facing content so they don't gate first-read comprehension.

BUILDING.md also gets a Go 1.26+ bump (was 1.25+) plus a note that GOTOOLCHAIN=auto handles older system Go.

Deliberately not in scope

Borrowed-organization-only from vm0's README; skipped the SaaS-style elements that don't fit a Linux profiler:

  • No giant centered SVG hero (a small banner would be fine later; not now).
  • No audience-segmented sections ("for founders / for sales").
  • No Discord-as-primary-channel, no Trendshift, no contrib.rocks (one-engineer project, not the right signal).
  • No "your data stays yours" SaaS pitch — though the SECURITY.md and README's value prop both call out the local-only / no-telemetry stance, which is the substance of that claim.
  • No external marketing site links.

Diff shape

LICENSE              + 202 (new, canonical Apache 2.0)
CONTRIBUTING.md      +  76 (new)
CODE_OF_CONDUCT.md   + 130 (new, Contributor Covenant 2.1)
SECURITY.md          +  56 (new)
.gitignore           +  14 / 0
README.md            + 130 / -110 (rewrite)
BUILDING.md          +   1 / -1 (Go version bump)

Test plan

  • git status clean after rebuilding test workloads (gitignore covers them)
  • CI: lint, build amd64+arm64, unit tests amd64+arm64, integration tests
  • Visual: render the README on github.com and confirm badges resolve, TOC anchors work, and section flow reads quickstart-first.

dpsoft added 4 commits May 3, 2026 13:13
The repo had no LICENSE, no contribution guide, no code of conduct, and
no security disclosure path. GitHub's community profile flagged all
four; downstream packagers and security researchers expect them.

- LICENSE: canonical Apache 2.0 text from apache.org.
- CONTRIBUTING.md: build/test/PR conventions, redirects to BUILDING.md
  and references existing review patterns. States in-scope vs out-of-
  scope work (no cluster-wide watchers, no telemetry) so feature
  requests get triaged consistently.
- CODE_OF_CONDUCT.md: Contributor Covenant 2.1, contact set to the
  maintainer's email + GitHub Security Advisories as alternatives.
- SECURITY.md: vuln reporting path (Security Advisory preferred,
  email fallback), explicit threat model, scope boundaries. Calls out
  that the agent runs with elevated kernel caps so privilege-escalation
  and kernel-DoS reports are taken seriously.
… test workload binaries)

These files keep showing up in 'git status' on local checkouts:

- isolate-*-v8.log: Node.js V8 logs from running the JS test workloads.
- pmu.txt: stray PMU capture some users redirect from the CLI.
- .codex: Anthropic CLI cache directory.
- test/workloads/go/{cpu_bound,io_bound}: built test-workload binaries.
  Their sources stay tracked; the binaries shouldn't be.

No production code change; cleanup only.
…e, separators

The README hit the user with an 80-line ASCII architecture diagram in
slot 2 — before they'd seen a single command. Reorder so a new reader
can install, run a profile, and pick this tool over alternatives
without scrolling past kernel-space internals.

New top-of-file:
- One-line italic tagline distinct from the prose intro.
- Badge row: CI, Tests, Go reference, Go version, license.
- Two-paragraph value prop, ending on the "no backend, no telemetry,
  no scrape config" stance that distinguishes us from Pyroscope/Parca.
- Auto-style table of contents.
- '---' separators between major sections (matches the visual hierarchy
  most well-organized Go-tooling READMEs use today).

New sections:
- 'Quickstart' (3 commands: build, setcap, capture) is the first
  content section. Anything substantive happens further down.
- 'What it does' — single table with all four modes (on-CPU, off-CPU,
  PMU, library) so readers don't reconstruct it from prose.
- 'vs the alternatives' — concrete comparison row-by-row against perf
  record / parca-agent / pyroscope-ebpf / py-spy. Helps people pick the
  right tool, which is more honest than vague positioning.
- 'Profiling inside a Kubernetes pod' — short subsection mentioning
  the namespace-aware --pid + pprof k8s labels we just shipped, with
  links rather than re-explaining.

The architecture deep-dive ASCII diagram and procmap.Resolver
narrative are preserved verbatim, just moved below 'Library usage' so
they don't gate first-read comprehension. Contributing / Security /
License footer sections link to the new community files in the
previous commit.

BUILDING.md: bump 'Go 1.25+' to 'Go 1.26+' (matches go.mod) and note
that GOTOOLCHAIN=auto handles older system Go.
…u can do'

The 'vs the alternatives' table read like a competitive ad — useful as
a one-time decision aid, but it doesn't help anyone who's already on
this page figure out what to actually do with the tool. Replace with
six concrete workflows perf-agent is built for, each tied to specific
modes/flags and a real production scenario:

- 🔥 On-demand production profiling (sidecar attach, --inject-python)
- 💤 Off-CPU stalls and blocking analysis (--offcpu)
- 🐍 Cross-language flame graphs (DWARF + Python + Node + Go)
- 📊 Hardware-counter investigations (--pmu, IPC, rq latency)
- 🧪 Differential profiling / sample-based PGO (high-fidelity pprof)
- 🐳 Sidecar profiling inside Kubernetes pods (NSpid + k8s labels)

Drop the redundant 'What it does' modes table — the use cases cover
what each mode is for; the [Flags](#flags) table covers the knobs.

Add a small experimental-track callout at the top mentioning GPU
profiling is in active development and linking the design spec, so
readers know that surface area is coming without it being part of the
stable feature list.

Update the TOC accordingly.
@dpsoft dpsoft force-pushed the chore/readme-and-community branch from ad2fe6b to a70f94c Compare May 3, 2026 19:52
The repo accumulated 24 doc files that no longer earn their keep:
- 10 implementation plans for features that already shipped (s3-s9
  dwarf walker, ehcompile, ehmaps, dwarfagent integration, off-CPU
  DWARF, system-wide DWARF, pprof fidelity, unwind-auto bench, lazy
  CFI, Python perf injector, k8s pid+labels).
- 5 design specs for those same shipped features. Once code lands,
  the spec stops being the source of truth — the README and the
  code itself are.
- 3 .excalidraw files (architecture, cpu-vs-offcpu, pmu-counters)
  + 1 docs/img.png. The README's ASCII architecture diagram is the
  current source of truth; maintaining a parallel visual artifact
  in JSON-positional source-of-truth form (Excalidraw) was overhead
  with no payoff. Future diagram edits happen in-place in the README.
- 2 design docs (dwarf-unwinding-design.md,
  unwind-auto-refinement-design.md) for the same shipped features.

Kept in docs/:
- python-profiling.md — referenced from the README, still load-bearing
  for users running --inject-python.
- docs/superpowers/specs/2026-04-25-gpu-profiling-design.md — forward-
  looking, GPU profiling is in active development.
- docs/superpowers/specs/2026-04-25-s10-pgo-converter-idea.md —
  forward-looking sketch, not yet implemented.

CONTRIBUTING.md: soften the "design specs in docs/superpowers/specs/"
language so it reflects the new policy (forward-looking specs only,
shipped ones get retired) instead of pretending the directory is
populated.

Net delete: 24 files. The repo's docs/ tree now lists three files
total — exactly what's still load-bearing.
@dpsoft dpsoft force-pushed the chore/readme-and-community branch from a70f94c to d83af86 Compare May 3, 2026 20:07
@dpsoft dpsoft marked this pull request as ready for review May 3, 2026 20:19
@dpsoft dpsoft merged commit e1ef04b into main May 3, 2026
10 checks passed
@dpsoft dpsoft deleted the chore/readme-and-community branch May 3, 2026 20:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant