docs: README rewrite + community files (LICENSE, CONTRIBUTING, CoC, SECURITY)#15
Merged
Conversation
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.
ad2fe6b to
a70f94c
Compare
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.
a70f94c to
d83af86
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 withCAP_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:
---separators between H2s (visual hierarchy).New sections:
perf record/ parca-agent / pyroscope-ebpf / py-spy. Helps people pick the right tool, which is more honest than vague positioning.--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.Resolvernarrative are preserved verbatim — just moved below user-facing content so they don't gate first-read comprehension.BUILDING.mdalso gets a Go 1.26+ bump (was 1.25+) plus a note thatGOTOOLCHAIN=autohandles 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:
Diff shape
Test plan
git statusclean after rebuilding test workloads (gitignore covers them)