Repository navigation
docs: add issue/PR templates, SECURITY, troubleshooting, CONTRIBUTING and CoC - #29
Merged
Merged
Conversation
added 5 commits
October 22, 2026 05:23
The entry existed only for one maintainer's local assistant workspace, so it leaked a private directory name into every clone and forced other contributors to carry an ignore rule they never needed. Local-only paths belong in .git/info/exclude, which is per-clone and never committed. `.workbuddy/` is ignored there instead; nothing about the build changes.
The first real bug report (#25) was a single screenshot. It turned out to be diagnosable - a macOS "Keychain Not Found" alert raised on behalf of the ipatool CLI - but only after someone read the image and guessed which layer produced it. A report that cannot name the app version, the OS, or the engine version costs a round-trip for every field. - .github/ISSUE_TEMPLATE/bug_report.yml asks for exactly those fields, plus reproducibility and the exported log, and asks reporters to say whether the problem is a vulnerability (those must not be public). - .github/ISSUE_TEMPLATE/config.yml turns off blank issues and points security reports, packaging questions and the install notes at the right place, so the form is not bypassed by an empty issue. - CONTRIBUTING.md documents the commands CI runs, which layer code belongs in, the two review rules that keep coming up (treat every IPC input as untrusted; say so when user-visible behaviour changes), and what makes a useful test. Documentation only: typecheck, lint and the full suite (482 tests) are unchanged and pass.
Two documents the project was missing, both aimed at the same problem: a report or a bug that costs a round-trip because the basic facts are not written down anywhere. SECURITY.md states what is in scope and what is not. The project ships unsigned binaries, downloads the engine at runtime and verifies it against a published SHA-256, and refuses to store credentials without an OS keystore - all deliberate, so "the binary is unsigned" or "the checksum failed" are not vulnerabilities. It also names the things that *are*: bypassing the verification, or reaching the credential store. It points at GitHub private vulnerability reporting, and says plainly that there is no bounty. docs/troubleshooting.md covers the four failures that actually get reported: the engine not being found or failing verification; macOS "Keychain Not Found" during sign-in (the alert comes from the ipatool CLI, not the app - it needs a default login keychain); the macOS "app is damaged" Gatekeeper message; and the network error codes, mapped to what to do about each. The error-code table was checked against IpatoolErrorCode and ENGINE_ERROR_CODES rather than written from memory, and both READMEs now link these documents.
CONTRIBUTING.md asks for "what changed / how it was verified / what was not verified", but the box people actually type into had no prompts. This adds them, plus a checklist that mirrors what CI enforces. The "Not verified" section is deliberate: "no macOS machine, so codesign was not run" is useful information, while silence about it reads as a claim that everything was tested.
The issue form now asks people to be specific about failures, which only works if the project is a place where being wrong is safe. This states the expectation and gives a private reporting route. Adapted from Contributor Covenant 2.1; enforcement contact is the maintainer.
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.
What changed
Adds the contribution and support documents the repository was missing — an issue form and its config, a pull request template, CONTRIBUTING, SECURITY, a troubleshooting guide and a code of conduct — links them from both READMEs, and drops the local-only
.workbuddy/entry from.gitignore.Why
Refs #25, which is the case that motivated this: the report was a single screenshot. The screenshot did identify the failure (macOS "Keychain Not Found", raised on behalf of the
ipatoolCLI, not the GUI), but getting the app version, OS, engine version, reproducibility and logs out of the reporter was one round-trip per field. The issue form now asks for all five up front.SECURITY.md exists for the other half of the same problem: without a written boundary, reports of "the build is unsigned" or "the checksum failed" look like vulnerabilities, while the ones that matter — bypassing verification, reaching the credential store — go unnamed. Troubleshooting covers the four failures that actually get reported, with the error-code table checked against
IpatoolErrorCodeandENGINE_ERROR_CODESrather than written from memory.docs/troubleshooting.mdalso documents the keychain case from #25 end to end, including the warning not to press "Reset To Defaults".How it was verified
npm run typecheck,npx eslint src tests scripts,npm run build— exit 0.npx vitest run— 482 passed, 2 skipped (Windows). Unchanged frommain; no source files were touched, so this is a regression check rather than new coverage.js-yaml: 10 body fields, 2 top-level keys.errors.ts/types.ts(proxyanddiskwere added to the table after checking the rules).Not verified
README.md, the release notes and the code, not re-tested on a Mac or a clean Windows machine..workbuddy/from.gitignoreon other contributors. Nothing in the build references that path, but anyone who kept a directory of that name there will now see it as untracked.Checklist
npm run typecheckpassesnpm testpasses (coverage gate included)npm run lintpassessrc/shared/has tests — n/a, no source changes