Open the project to contributors - #1
Open
eliseorobles wants to merge 3 commits into
Open
Conversation
The repository had all the writing done and none of the surfaces open: no CI, no issue templates, no code of conduct, and a README that said contributions were welcome without saying where to start. A vague invitation leaves the best-evidenced newcomer barrier — finding a way in — completely intact. CI runs on a macos-26 runner pinned to Xcode 26.3, the same build the suite is verified against. The second job is worth as much as the first: it fails if the private centering tool, any card image, or the internal working documents ever become tracked. Those guards exist today only in .gitignore and a pre-commit hook that a fresh clone does not have until someone remembers to point core.hooksPath at it. CI is the half that cannot be forgotten. The README now names the three things standing between this and the best open-source scanning app on the Mac — one supported scanner, no downloadable binary, and two review actions that need a mouse — and says where each one lives, because none of them fail for architectural reasons. Also states plainly that a scanner is not required. That is the most common reason someone assumes they cannot help, and it is wrong: 251 tests run without one, and --synthetic exercises the real crop, verdict, deskew and publication path. SPEC.md pointed at a research file that is no longer published. Fixed.
CI found this on its first run, which is the argument for having it: the deskew floor test asserted the published pixels equal the source exactly, and that held on one machine and failed on the runner reading 17 where 18 went in. Nothing was resampled. The fixture is a lossless PNG, `crop` publishes JPEG, and JPEG at quality 1.0 is still a DCT round-trip through YCbCr — it lands a flat region within a level or two rather than on it. The difference came from the encoder, and which side of a rounding boundary a value falls on is not a property this project gets to depend on. The tolerance is 2 and the comment says why it is small: interpolating a 0.1° rotation moves an edge pixel by whole levels of contrast, so it still catches a resample. Verified by dropping the floor to 0.01 and re-running — the test goes red. It goes red at `tiltDegrees == nil` and the output-dimension checks rather than in the pixel loop, which is worth knowing: those assertions are exact, platform-independent, and are what actually proves the crop was a copy. The pixel comparison is a secondary guard and the comment now says so instead of implying it carries the proof.
The badge and the required checks both waited on a real green run rather than being added on the assumption of one. A badge that has never passed is worse than no badge.
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.
What this changes
Adds the surfaces a public repo needs and this one was missing: CI, issue forms, a code of conduct, and a README section that names where to start.
Why
The repository had all the writing done and none of the surfaces open — zero issues, zero CI, nine default labels. A "contributions welcome" line leaves the best-evidenced newcomer barrier (finding a way in) fully intact.
Two things worth calling out:
centering/, any card image, or the internal working docs ever become tracked. Those guards live today only in.gitignoreand a pre-commit hook a fresh clone doesn't have. This is the half that can't be forgotten.Also fixes
SPEC.md§8, which pointed at a research file that is no longer published.How it was verified
swift test -c release— 251 tests in 29 suites, exit 0centering/, a card image, and a trackedCLAUDE.mdHardware: no scanner — docs, CI and templates only. The one code-adjacent change is a doc fix.
Note
CI has never run before, so this PR is its first execution. If the
macos-26image has retired Xcode 26.3, the Select Xcode step fails loudly and lists what's installed — that's a one-line pin change, not a redesign. Don't add a build badge until a run is actually green.