Skip to content

Commit a110d21

Browse files
ozeranskiiozeranskii
authored
docs(readme): add OpenSSF Best Practices passing badge (#111)
1 parent c80cf60 commit a110d21

6 files changed

Lines changed: 473 additions & 5 deletions

File tree

‎GOVERNANCE.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Governance
2+
3+
This document describes how the httptap project is organized, who makes
4+
decisions, and how those decisions are made. It is intentionally minimal and
5+
reflects the project's current scale: a small open-source utility maintained
6+
primarily by a single person.
7+
8+
If the project grows, this document will be updated accordingly — proposals
9+
to amend governance are themselves accepted as pull requests against this
10+
file.
11+
12+
## Project Type
13+
14+
httptap is an independent open-source project distributed under the
15+
[Apache License 2.0](LICENSE). It is not currently part of any foundation,
16+
company, or consortium.
17+
18+
## Roles
19+
20+
### Maintainer
21+
22+
The maintainer is responsible for the long-term direction of the project,
23+
has write access to the repository, and is accountable for releases.
24+
25+
- **Current maintainer:** Sergei Ozeranskii
26+
([@ozeranskii](https://github.com/ozeranskii))
27+
28+
Responsibilities:
29+
30+
- Triage issues and pull requests.
31+
- Review, approve, and merge contributions.
32+
- Cut releases and publish to PyPI.
33+
- Respond to vulnerability reports per [SECURITY.md](SECURITY.md).
34+
- Keep [ROADMAP.md](ROADMAP.md) and project documentation current.
35+
- Enforce the [Code of Conduct](CODE_OF_CONDUCT.md).
36+
37+
### Reviewer
38+
39+
Reviewers are trusted contributors who review pull requests on behalf of the
40+
maintainer. Reviewers do **not** have write access; their reviews are
41+
advisory and must still be accepted by the maintainer before merge.
42+
43+
The project currently has no formal reviewers beyond the maintainer.
44+
Candidates are invited after a sustained track record of high-quality
45+
contributions.
46+
47+
### Contributor
48+
49+
Anyone who submits an issue, pull request, or documentation improvement.
50+
Contribution requirements are documented in
51+
[CONTRIBUTING.md](CONTRIBUTING.md).
52+
53+
## Decision Making
54+
55+
The project uses a **benevolent dictator for life (BDFL)** model: the
56+
maintainer has final say on all changes. In practice, most decisions are
57+
consensus-driven through pull request review, and disagreements are
58+
resolved by public discussion on GitHub.
59+
60+
- **Day-to-day changes** (bug fixes, documentation, minor features): merged
61+
once the maintainer approves the pull request and CI passes.
62+
- **Significant changes** (new public API, breaking changes, dependency
63+
additions): discussed in a GitHub issue before implementation.
64+
- **Scope changes** (items moving in or out of [ROADMAP.md](ROADMAP.md)):
65+
decided by the maintainer after community feedback on the relevant issue.
66+
- **Governance changes** (this file, CODE_OF_CONDUCT, SECURITY, LICENSE):
67+
require explicit maintainer approval of a pull request.
68+
69+
## Contribution Process
70+
71+
See [CONTRIBUTING.md](CONTRIBUTING.md). In short:
72+
73+
1. Open or comment on an issue to signal intent for non-trivial work.
74+
2. Fork the repository and submit a pull request from a feature branch.
75+
3. Ensure `uv run pre-commit run --all-files` and `uv run pytest` pass.
76+
4. Address review feedback; the maintainer merges when ready.
77+
78+
Contributions are accepted under the inbound=outbound licensing model
79+
(Apache-2.0 for code, CC-BY-4.0 for documentation); no separate Contributor
80+
License Agreement (CLA) is required.
81+
82+
## Releases
83+
84+
Releases are cut by the maintainer using the automated release workflow in
85+
[`.github/workflows/release.yml`](.github/workflows/release.yml).
86+
87+
- **Cadence:** as-needed, typically every 2–6 weeks.
88+
- **Versioning:** [Semantic Versioning 2.0.0](https://semver.org).
89+
- **Channel:** [PyPI](https://pypi.org/project/httptap/) via OIDC Trusted
90+
Publishing (no long-lived API tokens).
91+
- **Supply chain:** releases are signed with Sigstore keyless signing and
92+
ship SLSA v1.0 build provenance attestations via
93+
`actions/attest-build-provenance`.
94+
- **Supported versions:** see [SECURITY.md](SECURITY.md).
95+
96+
## Continuity
97+
98+
To ensure the project can continue with minimal interruption if the current
99+
maintainer becomes unavailable:
100+
101+
- **Source code** is mirrored to every contributor's fork and to PyPI sdist;
102+
the repository can be forked and continued by anyone under Apache-2.0.
103+
- **Release infrastructure** relies on GitHub-native OIDC Trusted Publishing
104+
rather than long-lived secrets; a new maintainer with PyPI project
105+
ownership can continue releases without any key handoff.
106+
- **PyPI project ownership** can be recovered via PyPI's account recovery
107+
process (maintainer recovery email is on file with PyPI).
108+
- **Domain** (`httptap.dev`) and GitHub account recovery are covered by the
109+
maintainer's personal credential inheritance plan.
110+
- **Issue trackers and discussions** continue to work on GitHub without
111+
maintainer action.
112+
113+
In the event of prolonged maintainer absence (>30 days with no response),
114+
the community is encouraged to fork the project under Apache-2.0 and
115+
self-organize. Such a fork may request transfer of the `httptap` PyPI name
116+
from the PyPI administrators if the original project is abandoned.
117+
118+
## Code of Conduct
119+
120+
All participants — maintainer, reviewers, contributors, and commenters —
121+
are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
122+
123+
## Security Reporting
124+
125+
Vulnerabilities are reported privately via GitHub Security Advisories, as
126+
documented in [SECURITY.md](SECURITY.md). Public issue reports for
127+
security-sensitive bugs are discouraged.
128+
129+
## Amending This Document
130+
131+
Open a pull request. Non-trivial changes to governance should be discussed
132+
in an issue first so the community can weigh in.

‎README.md‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@
77
<table>
88
<tr>
99
<th>Releases</th>
10-
<th>CI &amp; Analysis</th>
10+
<th>CI &amp; Quality</th>
11+
<th>Security</th>
1112
<th>Project Info</th>
1213
</tr>
1314
<tr>
@@ -23,17 +24,25 @@
2324
<a href="https://github.com/ozeranskii/httptap/actions/workflows/ci.yml">
2425
<img src="https://github.com/ozeranskii/httptap/actions/workflows/ci.yml/badge.svg" alt="CI" />
2526
</a><br />
27+
<a href="https://codecov.io/github/ozeranskii/httptap">
28+
<img src="https://codecov.io/github/ozeranskii/httptap/graph/badge.svg?token=OFOHOI1X5J" alt="Coverage" />
29+
</a><br />
30+
<a href="https://codspeed.io/ozeranskii/httptap?utm_source=badge">
31+
<img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed Badge" />
32+
</a>
33+
</td>
34+
<td>
2635
<a href="https://github.com/ozeranskii/httptap/actions/workflows/codeql.yml">
2736
<img src="https://github.com/ozeranskii/httptap/actions/workflows/codeql.yml/badge.svg" alt="CodeQL" />
2837
</a><br />
2938
<a href="https://scorecard.dev/viewer/?uri=github.com/ozeranskii/httptap">
3039
<img src="https://api.scorecard.dev/projects/github.com/ozeranskii/httptap/badge" alt="OpenSSF Scorecard" />
3140
</a><br />
32-
<a href="https://codecov.io/github/ozeranskii/httptap">
33-
<img src="https://codecov.io/github/ozeranskii/httptap/graph/badge.svg?token=OFOHOI1X5J" alt="Coverage" />
41+
<a href="https://www.bestpractices.dev/projects/12474">
42+
<img src="https://www.bestpractices.dev/projects/12474/badge" alt="OpenSSF Best Practices" />
3443
</a><br />
35-
<a href="https://codspeed.io/ozeranskii/httptap?utm_source=badge">
36-
<img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed Badge" />
44+
<a href="https://www.bestpractices.dev/projects/12474">
45+
<img src="https://www.bestpractices.dev/projects/12474/baseline" alt="OpenSSF Baseline" />
3746
</a>
3847
</td>
3948
<td>

‎ROADMAP.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Roadmap
2+
3+
This document describes what httptap intends to do — and, equally
4+
importantly, what it does **not** intend to do — over roughly the next
5+
twelve months. It is intentionally light on dates and heavy on scope: the
6+
project is maintained by a single person in their spare time, so concrete
7+
schedules would be misleading.
8+
9+
The roadmap is living. Opening an issue to propose a change is welcome and
10+
is the preferred way to request scope adjustments. Merged scope changes are
11+
reflected here in the same pull request.
12+
13+
**Last reviewed:** 2026-04-12
14+
15+
## Mission
16+
17+
`httptap` is a diagnostic command-line tool that dissects a single HTTP
18+
request into its constituent phases (DNS, TCP connect, TLS handshake,
19+
server wait, body transfer) and renders those timings in a form suitable
20+
for humans, logs, or scripts. The mission is to make per-phase HTTP timing
21+
legible to a developer the same way a browser's waterfall makes it legible
22+
to a web author — but from the terminal, without a browser, and without
23+
pulling in a heavyweight framework.
24+
25+
## Current Phase: Maintenance & Polish
26+
27+
The project is stable and in active maintenance. The release cadence is
28+
dictated by:
29+
30+
- incoming bug reports and security updates,
31+
- dependency refreshes via Dependabot,
32+
- small quality-of-life improvements contributed by users or the maintainer.
33+
34+
There is no committed feature list. New functionality is added only when it
35+
clearly serves the mission and fits within the non-goals below.
36+
37+
## In Scope
38+
39+
The following themes are accepted as potential work. Specific items only
40+
materialize when the maintainer or a contributor actually picks them up.
41+
42+
- **Core timing accuracy** — refinements to httpcore trace hooks, better
43+
handling of HTTP/2 connection reuse, more precise fallbacks when direct
44+
timing is unavailable.
45+
- **Output formats** — additional machine-readable exporters (e.g.,
46+
Prometheus text format, OpenTelemetry traces) when driven by a concrete
47+
user need.
48+
- **Protocol support** — minor improvements to HTTP/1.1 and HTTP/2 behavior
49+
as upstream (`httpx`, `httpcore`) gains features; potential support for
50+
HTTP/3 if and when stable Python support lands.
51+
- **TLS diagnostics** — additional certificate and handshake details
52+
reported by default or under flags.
53+
- **Supply-chain hardening** — continuing improvements that raise the
54+
project's OpenSSF Scorecard and Best Practices posture.
55+
- **Documentation** — worked examples, troubleshooting recipes, and
56+
integration cookbooks.
57+
58+
## Non-Goals
59+
60+
These items are explicitly **out of scope**. Contributions in these
61+
directions will be declined politely so contributors don't waste effort.
62+
63+
- **Load testing / benchmarking** — httptap measures a single request; tools
64+
like `wrk`, `k6`, or `vegeta` already serve the benchmarking use case.
65+
- **Full curl replacement** — httptap aims for curl-compatible flags on the
66+
overlap that makes sense; it does not target feature parity with curl.
67+
- **Scripting / session runners** — multi-request workflows, cookies,
68+
scripting, or chainable request/response assertions belong in tools like
69+
`httpie` or `hurl`.
70+
- **Server-side tooling** — httptap is strictly a client. Proxying,
71+
mitmproxy-style interception, or server emulation are out of scope.
72+
- **GUI or TUI** — terminal output stays as Rich renders; no full-screen
73+
TUI and no graphical interface.
74+
- **Plugin ecosystem** — the Python Protocol interfaces are explicitly
75+
supported as a programmatic extension point, but a dynamic plugin loader
76+
or plugin registry is not planned.
77+
- **Non-HTTP protocols** — gRPC, WebSocket, MQTT, etc. are out of scope.
78+
79+
## Deprecation Policy
80+
81+
- Public API and CLI flags follow Semantic Versioning 2.0.0.
82+
- Breaking changes ship only in a major version bump (`X.0.0`) with
83+
migration notes in `CHANGELOG.md` and the release notes.
84+
- Deprecations are announced at least one minor release before removal and
85+
emit a runtime warning where practical.
86+
87+
## Supported Versions
88+
89+
See [SECURITY.md](SECURITY.md) for the currently supported minor series.
90+
91+
## Python Support
92+
93+
The project targets the Python versions currently labelled as supported by
94+
the [Python release calendar](https://devguide.python.org/versions/) plus
95+
the current pre-release series (3.10–3.15 at the time of writing). Older
96+
Python versions are dropped only at major releases and only when required
97+
by a dependency.
98+
99+
## How to Propose a Change
100+
101+
Open a [GitHub issue](https://github.com/ozeranskii/httptap/issues/new) with
102+
the "enhancement" label describing the problem, the proposed direction, and
103+
(if applicable) why it fits within the mission and does not cross a
104+
non-goal. The maintainer will respond with acceptance, pushback, or a
105+
request for more detail.
106+
107+
Significant changes are expected to land as a pull request only after the
108+
proposal has been discussed.

0 commit comments

Comments
 (0)