Adopt the Ares2 pull request and release templates - #11
Merged
Merged
Conversation
The repository has no templates, so every pull request and every release describes itself in whatever shape its author picked. Ares2 has solved this already, and the two projects are read by the same people, so the structure should be the same one. Section structure, heading order and the meta-rules are taken over unchanged: every section is required and states what to write when it does not apply, character limits are counted after the instruction comments are stripped, and each section says who has to be able to follow it. What changed is the subject: the Ares originals explain themselves in terms of Java, Maven, Gradle, AspectJ and JUnit, which would send a Phobos contributor looking for things this repository does not contain. The Phobos versions name the layers that exist here instead: the filesystem sandbox, the LD_PRELOAD network filter, the timeout wrapper, the policy parser, the prune phase and the images. Three additions specific to a sandbox: - The testing manual asks for the container invocation in full. Whether a run used --privileged, --cap-add or --security-opt decides whether the boundary held or was switched off, so a manual that omits it cannot be read. - The manual and the checklist both ask for both directions. A sandbox that denies everything passes any one-sided test, so the forbidden case being denied and the permitted case still working are only meaningful together. - The release notes ask whether the release changes what the sandbox permits, in the opening paragraph rather than further down. Section 5 has no counterpart to the JaCoCo table: this repository is tested by the shell suites under tests/, so the table records passed, failed and skipped per suite, plus the container invocation, kernel and architecture the run happened on, because the enforcement mechanism depends on all three. CODEOWNERS is taken over verbatim. The "Protect main: require pull request review" ruleset requires a code owner review, and without this file that part of the rule has nothing to match, so the two belong together.
added 3 commits
September 8, 2026 15:44
Two corrections to the previous commit, both found by comparing against the Ares2 originals rather than by reading my own version again. Section 4 had lost its fill-in scaffold. Ares2 ends the section with Prerequisites, Steps, Expected result, Negative case and the modes exercised, so an author is asked for the negative case in the body of the pull request, where a reviewer looks for it. My version dropped all of it and then reintroduced the same idea as a checklist tick, which is weaker: a tick claims the case was covered, the scaffold makes the author write down what it was. The scaffold is back, with the four Ares enforcement combinations replaced by the three layers this project composes, each of which can be disabled on its own. Section 4 had also lost both recurring meta-rules, its character limit and the "simple words" paragraph, even though the template states in its own header that they are repeated in every section where they apply. The counts now match Ares2 exactly: seven limits, six "simple words" paragraphs, eleven "always required" statements. The template check itself is adopted, which is what makes the template binding rather than advisory: - .github/scripts/CheckPullRequestTemplate.java differs from the Ares2 version in a single line, the escape phrase for section 5, because this repository has no production Java code to report coverage for and answers that section with "No behaviour covered by the suites changed". - .github/workflows/pullrequest-template.yml is taken over unchanged. It runs the checker in single-file source mode, so there is no build step, exempts Renovate and Dependabot at step level so a required check never hangs pending, and passes the pull request body through the environment rather than interpolating it into the shell, since a fork author controls it verbatim. Running the checker locally against the open pull requests: #11 and #12 pass, #8, #9 and #10 do not yet, and their descriptions are being brought into shape separately.
A second comparison against the Ares2 originals, this time sentence by sentence rather than by reading my own version again. It found three things the first pass had removed although nothing about them was Ares-specific. The release template lost the most. Its "Problems" section had been reduced to a single sentence and, worse, its rule had been inverted: Ares2 states "Never write 'None' here: a release with nothing to say under Problems does not need notes", while my version invited exactly that. Also restored there: the instruction to bound an improvement by its limitation, which matters more here than in Ares2 because a partial hardening in a sandbox reads as a guarantee; the rule that a change failing closed belongs under breaking changes even when it is technically a fix; and the requirement to list removals by name and to show the before and the after. The pull request template lost two sentences of the testing manual: asking for one tool rather than three and giving every command in full, and the rule that a claim which cannot be observed anywhere either gets a diagnostic or does not get asked for. The recurring meta-rules now match Ares2 exactly: seven limits, six "simple words" paragraphs, eleven "always required" statements, in the same sections. The remaining difference in length is the Java-specific material that has no counterpart here: the JaCoCo counters, the Maven coordinates, the browser and Windows-path guidance, and the four enforcement combinations, replaced by the three layers this project composes.
Going through the sentences that were reworded rather than replaced, most had a reason and four did not. The worst of them weakened the text: Ares2 tells a reviewer to look at the result "not at an exit code", which had become "not only at an exit code", and the sentence before it listed the exit code as one of the observable results, directly contradicting the advice that follows. Both are back to the original wording. Also restored: "where it is observable" instead of the shortened "where", "better error output" and "better diagnostics" instead of a needless elaboration, "a simpler dependency or CI setup", "the run output" instead of the truncated "the output", and "all four" for the four boxes that are actually there. Of the 208 sentences in the two Ares2 templates, 181 are now taken over verbatim. The rest are the Java, Maven, JaCoCo, browser and Windows material that has no counterpart in this repository, and eleven substitutions of a term this project uses differently: layers rather than modes, run rather than build, sandbox rather than security tool, image build rather than account.
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
1 participant
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.
Summary
The repository has no templates, so every pull request and release describes itself in whatever shape its author picked. Ares2 has solved this, and both projects are read by the same people, so the structure should be the same one. Adds the pull request and release templates, CODEOWNERS, and the check that makes the template binding rather than advisory.
Linked issues
No linked issues.
1. Problem
Nothing is broken. Two gaps made this worth doing.
Pull requests and releases here have no agreed shape, so a reader cannot compare two of them, and an author has to decide each time what a reviewer needs. Ares2 answers that question already and the answer is a good one.
Second, I enabled the "Protect main: require pull request review" ruleset on this repository, copied from Ares2. It requires a code owner review, and without a CODEOWNERS file that part of the rule has nothing to match, so it silently does nothing.
2. Improvement from the user's perspective
No Improvement from the user's perspective. This changes how contributions are described, not how Phobos behaves.
3. Improvement from the maintainer's perspective
Reviewers get the same sections in the same order in every pull request, and those sections ask for what is actually hard to review here: which layer is at fault, what the container invocation was, and what must still be rejected. The check turns that from a convention into a gate. Release notes become comparable between versions, and the code owner rule starts working.
4. Testing manual
Prerequisites
Steps
gh pr view 9 --json body --jq .body > body.md.PR_BODY="$(cat body.md)" java .github/scripts/CheckPullRequestTemplate.java.Expected result
Step 2 against #9 reports missing section headings, one
::error::line per absent section, and exits non-zero. Step 3 reports "All 10 required sections are present and filled in." and exits zero. That pair is the point: the checker has to reject a body that ignores the template, not merely accept one that follows it.Negative case (what must still be rejected)
A body that omits a section, that leaves a section empty, or that exceeds a section's character limit must fail. A body that answers a section with the template's own escape phrase, for example "No linked issues", must pass, because every section is required and a section that does not apply is answered rather than deleted.
Layers exercised
No layer-specific behaviour changed.
5. Test case coverage regarding this PR
No behaviour covered by the suites changed.
Breaking changes and migration
No breaking changes or migration.
Checklist
README.md, the comments incore/) was updated where the change is user-facing.Review progress