Skip to content

Commit 8fa46d9

Browse files
committed
docs: the contributor-facing docs stop promising things the project cannot do
Smell-audited: 2: this is the ungated-negative-doc-claim class (.dev/lessons/2026-08-03) caught at the last possible moment. Three documents made commitments that outlived the project, and the version bump would have shipped them into the final tag. Depth 2 rather than 1 because SECURITY.md is not a documentation defect — a policy that promises fixes is one someone can rely on while waiting for a patch that will never come. Found while sweeping demo references: CONTRIBUTING.md opens with "Issues and Pull Requests are open." Issues are disabled on this repository and always were (verified via the API: has_issues=false), so the sentence was false, and the divergence-report link it offered led to a form nobody can open. - **SECURITY.md** claimed `main` and the newest 1.x line were supported and that fixes land in the next release cut from `main`. Neither is true and neither can become true. It now says plainly that no version is supported and there will be no fixes including for critical vulnerabilities, and that migrating off is the fix. The threat model and scope sections are kept and relabelled for forks, because those parts are still accurate. It also points vulnerabilities in the embedded engine at zwasm, which IS maintained and can still act on them — the one report that remains worth filing. - **CONTRIBUTING.md** becomes a fork guide. The build, gate and test-layout sections were correct and are the things a fork would otherwise reverse-engineer, so they stay (and gained the two properties worth knowing before changing anything: dual-backend e2e, and clojure.core diffed against real clj). The PR-workflow and "what helps a PR land" sections describe a review that will not happen, and are gone. - **PULL_REQUEST_TEMPLATE.md** said PRs were "currently PAUSED" and asked people to come back through Discussions. That framing promised a resumption. - **ISSUE_TEMPLATE/config.yml** asserted "Issues are open" in a directory that does not render at all. The templates are kept deliberately — a fork enabling Issues gets a working set — and the comment now says so. - **docs/clojure_vs_clojurewasm.md** described Part 2 gaps as "scheduled" and "on the roadmap". Nothing is scheduled; they are what was planned and never built, which is still useful to a fork as intent.
1 parent 153ae71 commit 8fa46d9

5 files changed

Lines changed: 111 additions & 95 deletions

File tree

‎.github/CONTRIBUTING.md‎

Lines changed: 50 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,19 @@
1-
# Contributing to ClojureWasm
1+
# Working on ClojureWasm
22

3-
Thanks for your interest. **Issues and Pull Requests are open.** This is a
4-
small project, so replies can take a while — but the queue is real and it gets
5-
read.
3+
> [!IMPORTANT]
4+
> **ClojureWasm is no longer maintained, so there is nothing to contribute
5+
> *to*.** Issues and Pull Requests are disabled and always were — deliberately,
6+
> because they could not be serviced. Nothing will be merged here.
7+
>
8+
> **Fork it.** The licence (EPL-2.0) asks no permission and the project asks no
9+
> credit. This document is kept because everything below still works and is what
10+
> you would otherwise have to reverse-engineer: how to build it, how to run the
11+
> gate, and where the design is written down.
612
7-
## The most useful thing you can do
13+
## Building and testing
814

9-
**Report Clojure code that behaves differently here than on the JVM.**
10-
11-
ClojureWasm targets behavioural equivalence with JVM Clojure on the
12-
user-observable surface. Every divergence you find is either a bug or a gap
13-
that has not been written down yet — and finding them from the outside is worth
14-
more than anything else, because a project cannot easily see its own blind
15-
spots.
16-
17-
There is a [Clojure divergence issue template](https://github.com/clojurewasm/ClojureWasm/issues/new?template=divergence.yml)
18-
that asks for the three things that make such a report actionable: the
19-
expression, what `cljw` prints, and what a JVM REPL prints.
20-
21-
Some differences are deliberate — check
22-
[`docs/clojure_vs_clojurewasm.md`](../docs/clojure_vs_clojurewasm.md) first. If
23-
one is listed there and you think the reasoning is wrong, that is a good
24-
Discussion.
25-
26-
## Working on the code
15+
Everything here is current and verified — it is the same gate the final release
16+
was cut on.
2717

2818
```sh
2919
direnv allow # one-time: load Zig 0.16.0 via Nix (or: nix develop)
@@ -33,63 +23,60 @@ bash test/run_all.sh --serial-e2e # the full gate; must be green before
3323

3424
For a quick loop while iterating, `bash test/run_all.sh --smoke <e2e-step>`
3525
runs the unit tests, the dual-backend differential oracle, the linter, and the
36-
one end-to-end step you touched — tens of seconds instead of ~20 minutes. Run
37-
the full gate before you open the PR.
26+
one end-to-end step you touched — tens of seconds instead of ~20 minutes.
3827

39-
Branch from `main` as `develop/<short-slug>`, open a PR, and let CI run. CI
40-
runs the same gate on macOS and Linux; a green CI is what merges.
28+
CI (`.github/workflows/ci.yml`) runs that same full gate on macOS and Linux, and
29+
runs exactly one configuration everywhere, so a green CI and a green local gate
30+
mean the same thing.
4131

42-
### What we do **not** ask of you
32+
### Where the tests live
4333

44-
This repository is developed largely by an autonomous loop working under
45-
written guardrails, and that loop follows conventions that exist to keep *it*
46-
honest. **None of them apply to your contribution:**
34+
- **Unit tests** in `test "..."` blocks next to the code they cover.
35+
- **CLI behaviour** in `test/e2e/*.sh`.
36+
- **`clojure.core` behaviour** additionally as a line in the relevant corpus
37+
under `test/diff/clj_corpus/`, which is re-checked against a real `clj`.
38+
- The taxonomy, including which kinds of assertion are known to rot, is in
39+
[`.claude/rules/test_taxonomy.md`](../.claude/rules/test_taxonomy.md).
4740

48-
- You do not need a `Smell-audited:` line in your commit message.
49-
- You do not need to add a row to `.dev/debt.yaml`.
50-
- You do not need to write an ADR, a per-task note, or a ROADMAP amendment.
51-
- You do not need to match the commit-message style of the surrounding history.
41+
Two properties of the suite are worth knowing before you change anything, since
42+
they are what caught most of the bugs in this project's history: every
43+
end-to-end test runs on **both** the tree-walking interpreter and the bytecode
44+
VM and fails if they disagree, and `clojure.core` behaviour is diffed against
45+
real JVM Clojure rather than against hand-written expected values.
5246

53-
Write a clear commit message, keep the gate green, and that is enough. If a
54-
change turns out to need a design record, writing it is the maintainer's job,
55-
not yours.
47+
### Conventions you can ignore
5648

57-
### What helps a PR land
58-
59-
- **One concern per PR.** A 30-line fix with a test merges; a 600-line
60-
refactor bundled with a fix stalls.
61-
- **A test that fails before your change and passes after it.** The test
62-
taxonomy is in [`.claude/rules/test_taxonomy.md`](../.claude/rules/test_taxonomy.md);
63-
in short, unit tests live in `test "..."` blocks next to the code and CLI
64-
behaviour lives in `test/e2e/*.sh`.
65-
- For a `clojure.core` behaviour change, **a line in the relevant corpus under
66-
`test/diff/clj_corpus/`**, so the behaviour stays checked against real `clj`
67-
from then on.
68-
69-
A note on provenance: much of this codebase is machine-written under human
70-
review and direction. Contributions from people are very welcome and are
71-
reviewed the same way — on whether the code is right, not on who wrote it.
49+
Much of this repository was written by an autonomous loop under written
50+
guardrails, and the history reflects conventions that existed to keep *it*
51+
honest — `Smell-audited:` commit trailers, `.dev/debt.yaml` rows, ADRs,
52+
per-task notes. **None of it binds a fork.** They are documentation of how the
53+
work was done, not a process you inherit.
7254

7355
## Design context, if you want it
7456

7557
Load-bearing decisions are recorded as ADRs under
7658
[`.dev/decisions/`](../.dev/decisions/); the plan and its principles live in
7759
[`.dev/ROADMAP.md`](../.dev/ROADMAP.md); the development loop itself is
78-
described in [`.claude/CLAUDE.md`](../.claude/CLAUDE.md). None of this is
79-
required reading to send a patch — it is there if you want to know why
80-
something is the way it is.
60+
described in [`.claude/CLAUDE.md`](../.claude/CLAUDE.md). Deliberate
61+
divergences from JVM Clojure — the ones that are decisions rather than bugs —
62+
are catalogued in
63+
[`docs/clojure_vs_clojurewasm.md`](../docs/clojure_vs_clojurewasm.md); read it
64+
before treating a difference as a defect.
65+
66+
Nothing here is required reading. It is there so a fork does not have to
67+
re-derive why something is the way it is, and `.dev/debt.yaml` in particular is
68+
an honest list of what was known to be unfinished.
8169

8270
## Getting in touch
8371

84-
Open-ended questions belong in
85-
[GitHub Discussions](https://github.com/clojurewasm/ClojureWasm/discussions);
86-
the wider Clojure community also gathers on the
72+
[GitHub Discussions](https://github.com/clojurewasm/ClojureWasm/discussions)
73+
stays open and may go unanswered; the wider Clojure community gathers on the
8774
[Clojurians Slack](https://clojurians.slack.com).
8875

89-
Security problems should **not** be reported publicly — see
90-
[`SECURITY.md`](./SECURITY.md).
76+
There are no security fixes — see [`SECURITY.md`](./SECURITY.md), which is
77+
explicit about that.
9178

9279
## License
9380

94-
By contributing, you agree that your contributions are licensed under the
95-
Eclipse Public License 2.0 (see [LICENSE](../LICENSE)).
81+
The project is under the Eclipse Public License 2.0 (see
82+
[LICENSE](../LICENSE)), and stays that way. A fork inherits it.

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
1-
# Issues are open. Blank issues stay disabled so every report starts from a
2-
# template that asks for the one or two facts that make it actionable.
1+
# Issues are DISABLED on this repository and always were, so nothing in this
2+
# directory currently renders. The templates are kept for forks, which get a
3+
# working set of report forms the moment they enable Issues; this config keeps
4+
# blank issues off so every report starts from one of them.
35
blank_issues_enabled: false
46
contact_links:
57
- name: 💬 Questions, ideas, "is this supposed to work?"

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
<!--
2-
Pull Requests are currently PAUSED for ClojureWasm.
2+
ClojureWasm is no longer maintained, and Pull Requests are disabled here.
3+
This is not a backlog or a pause — nothing will be reviewed or merged.
34
4-
ClojureWasm is a small, resource-limited project and cannot review external
5-
PRs right now. Please close this PR and instead start a thread in Discussions:
5+
Fork it instead. EPL-2.0 asks no permission and the project asks no credit;
6+
see CONTRIBUTING.md for how to build it and run the gate.
67
7-
https://github.com/clojurewasm/ClojureWasm/discussions
8+
Discussions stay open and may go unanswered:
9+
https://github.com/clojurewasm/ClojureWasm/discussions
810
9-
and mention @chaploud. Thanks for understanding — we do want to hear about
10-
behaviour that differs from JVM Clojure, just through Discussions while PRs
11-
are closed.
11+
There are no security fixes either — SECURITY.md is explicit about that.
1212
13-
For security issues, see SECURITY.md (do not post exploit details publicly).
13+
(This template is kept for forks, which get it the moment they enable PRs.
14+
Replace this text with your own.)
1415
-->

‎.github/SECURITY.md‎

Lines changed: 39 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,49 @@
11
# Security Policy
22

3+
> [!IMPORTANT]
4+
> **ClojureWasm is no longer maintained, and no version is supported. There
5+
> will be no security fixes, including for critical vulnerabilities.**
6+
>
7+
> Do not deploy `cljw` where it is exposed to untrusted input. If you already
8+
> have, treat the migration off it as the fix — waiting for a patch here is
9+
> waiting for something that will not come.
10+
>
11+
> The rest of this document is kept because the threat model and the scope
12+
> boundaries are still accurate, and are the right starting point for anyone
13+
> forking the project. **A fork takes on its own security policy**; this one no
14+
> longer speaks for it.
15+
316
ClojureWasm (`cljw`) is a Clojure runtime with a **WebAssembly FFI**: it can
417
load and execute **untrusted `.wasm` bytecode** in the same process as the host
5-
(through the embedded zwasm engine), and — in embeddings like the public
6-
playground — it evaluates **untrusted Clojure source** in-process. Memory
7-
safety and sandbox integrity are therefore first-class concerns, and we take
8-
reports seriously.
18+
(through the embedded zwasm engine), and — in embeddings that accept
19+
user-submitted code, as the now-retired public playground did — it evaluates
20+
**untrusted Clojure source** in-process. Memory safety and sandbox integrity
21+
are therefore first-class concerns for anyone running it.
922

1023
## Supported versions
1124

12-
Security fixes land on the `main` branch and in the next release cut from it.
13-
Only the newest release line is supported — this is a small project and there
14-
is no backport branch.
25+
**None.** The project stopped at v1.10.1; there is no supported line, no
26+
backport branch, and nothing that will be cut from `main`.
1527

16-
| Version | Supported |
17-
|--------------------------------|-----------|
18-
| `main` | ✅ |
19-
| newest `1.x` release | ✅ |
20-
| any older release | ❌ |
28+
| Version | Supported |
29+
|-------------------------|-----------|
30+
| `main` | ❌ |
31+
| v1.10.1 (final release) | ❌ |
32+
| any earlier release | ❌ |
2133

22-
If you are on Homebrew, `brew upgrade clojurewasm/tap/cljw` puts you on the
23-
supported line.
34+
Note that the embedded WebAssembly engine, **zwasm**, is a separate project and
35+
[continues under its own maintainership](https://github.com/zwasm/zwasm) — a
36+
vulnerability in the engine should go there, and is worth reporting because that
37+
project can still act on it. What is unmaintained is `cljw`'s own runtime and
38+
the specific zwasm version this project pinned.
2439

2540
## Reporting a vulnerability
2641

27-
**Please do not open a public issue or Discussion for security problems.**
42+
Reports about `cljw` itself will not be acted on. If you find something anyway
43+
and want it recorded for the benefit of anyone forking the project, the channel
44+
below still exists — but expect no fix and no timeline.
45+
46+
**Please do not open a public Discussion for security problems.**
2847

2948
Report privately via GitHub's **[Private Vulnerability Reporting](https://github.com/clojurewasm/ClojureWasm/security/advisories/new)**
3049
(the "Report a vulnerability" button under the repository's *Security* tab).
@@ -41,12 +60,14 @@ Please include, where possible:
4160
- the observed impact (host memory corruption, Wasm sandbox escape, WASI
4261
capability bypass, denial of service, etc.).
4362

44-
We aim to acknowledge a report within a few days. Because this is a small,
45-
resource-limited project, please allow reasonable time for a fix before any
46-
public disclosure.
63+
There is no acknowledgement window and no fix window; see the notice at the top.
64+
You are under no obligation to delay disclosure on this project's behalf.
4765

4866
## Scope
4967

68+
The boundaries below describe what *would* have counted as a vulnerability in
69+
`cljw`. They are retained as a threat model for forks, not as an active offer.
70+
5071
In scope: host memory corruption from a malformed or adversarial `.wasm`
5172
module, Wasm sandbox / WASI-capability escapes, JIT code-generation bugs with a
5273
security impact, and memory-safety faults in the Zig runtime reachable from

‎docs/clojure_vs_clojurewasm.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -169,10 +169,15 @@ Note that Java *arrays* are implemented (type-erased — see AD-019), as is
169169

170170
A divergence listed in **Part 1** is *designed*: it derives from a project
171171
invariant and is pinned by a regression test, so it reads as a deliberate
172-
choice rather than a defect. A gap listed in **Part 2** is *scheduled*: it
173-
is on the roadmap (or, for the JVM-only corners, intentionally excluded).
174-
Anything not on this page that still differs from Clojure is a bug —
175-
please report it.
172+
choice rather than a defect. A gap listed in **Part 2** was *planned but never
173+
built* — it sat on the roadmap when the project stopped, or, for the JVM-only
174+
corners, was intentionally excluded. Anything not on this page that differs
175+
from Clojure is a bug that was never found.
176+
177+
Since the project is no longer maintained, treat both parts as a map for a fork
178+
rather than as a list of things about to change. Part 1 marks behaviour not to
179+
"correct" without first understanding the invariant behind it; Part 2 marks
180+
what is genuinely missing, with what was intended.
176181

177182
For the authoritative, machine-readable form of Part 1, see
178183
[`.dev/accepted_divergences.yaml`](../.dev/accepted_divergences.yaml); each

0 commit comments

Comments
 (0)