From e3fafe3a591a59c83766ba263ef27bfa2652b490 Mon Sep 17 00:00:00 2001 From: Austin Smith Date: Sat, 11 Jul 2026 16:22:02 -0700 Subject: [PATCH 1/2] add contribution templates and workflow guidance --- .github/ISSUE_TEMPLATE/bug_report.yml | 72 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/feature_request.yml | 31 ++++++++++ .github/pull_request_template.md | 18 ++++++ AGENTS.md | 47 +++++++++++++- 5 files changed, 167 insertions(+), 2 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..1b7f8a7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,72 @@ +name: Bug report +description: Report broken behavior, a regression, or a crash. +labels: + - bug +body: + - type: markdown + attributes: + value: | + Search open and closed issues first, and keep the report focused on one problem. + + - type: textarea + id: description + attributes: + label: Description + description: Explain what happened and what you expected to happen. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + description: Provide the smallest reliable reproduction you have. If the problem is intermittent, explain when it occurs. + placeholder: | + 1. + 2. + 3. + validations: + required: true + + - type: dropdown + id: platform + attributes: + label: Platform + options: + - macOS + - iPhone + - iPad + validations: + required: true + + - type: input + id: environment + attributes: + label: Environment + description: Include the OS version and Computer Solitaire version when known. + placeholder: macOS 26.2, Computer Solitaire 1.0 + validations: + required: true + + - type: dropdown + id: game + attributes: + label: Game variant + options: + - Klondike + - FreeCell + - Not game-specific + validations: + required: true + + - type: textarea + id: game-context + attributes: + label: Game settings or context + description: Include relevant settings such as draw mode or scoring mode, and describe the state of the game when the problem occurred. + + - type: textarea + id: evidence + attributes: + label: Additional evidence + description: Add relevant screenshots, recordings, logs, or crash reports. Redact sensitive information. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..0086358 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..2e3d634 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,31 @@ +name: Feature request +description: Propose a focused improvement or new capability. +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + Search open and closed issues first, and keep the request focused on one change. + + - type: textarea + id: problem + attributes: + label: Problem or goal + description: Explain what is difficult, missing, or not possible today. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed change + description: Describe the desired behavior and what would make the request complete. + validations: + required: true + + - type: textarea + id: context + attributes: + label: Additional context + description: Add related issues, screenshots, mockups, examples, or references. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..ecb8e69 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,18 @@ +## What Changed + + + +## Why + + + +## UI Changes + + + +## Validation + + diff --git a/AGENTS.md b/AGENTS.md index 91c691a..97584ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,6 +35,30 @@ This file defines hard project constraints for any coding agent working in this - Follow best practices by default: clear naming, small focused types/functions, and maintainable architecture. - Prefer robust, production-ready implementations over quick fixes. +## Branches, Commits, and Pull Requests + +- Use plain lowercase kebab-case for branch names. Keep names descriptive and do not include issue numbers, prefixes, or namespaces such as `feature/`, `fix/`, usernames, or agent names. +- Before every commit or amend, show the exact current diff and validation, then get explicit approval. Branch or pull-request requests are not commit approval; later changes require fresh approval. +- Never amend, rebase, squash, reset, rewrite history, or force-push without explicit approval for that exact operation. +- Write commit messages entirely lowercase. Use the imperative mood for the subject, keep each commit focused on one logical change, do not use type or scope prefixes, and do not end the subject with a period. Add a body when the reason or important tradeoffs are not clear from the subject. +- Keep each pull request focused on one coherent change. +- Write concise, specific, imperative pull request titles in sentence case. Do not use prefixes or trailing periods, and make the title understandable without the branch name. +- Pull request descriptions must include `What Changed`, `Why`, and `Validation`. Include `UI Changes` only when the pull request changes the UI. Keep descriptions concise, self-contained, complete, and accurate to the final diff. +- Link any related issues in the pull request description; do not include issue numbers in branch names. +- Review the complete diff before opening a pull request. Update the title and description whenever the scope changes, and remove unrelated changes. + +## Issues + +- Search open and closed issues before creating a new issue. +- Keep each issue focused on one problem or change. +- Use a concise, specific, sentence-case title without type prefixes. +- Give enough context to understand the issue without first inspecting the code. +- For bugs, describe the current and expected behavior. Include reproduction steps, environment details, the game variant and relevant settings, and supporting evidence when available. +- For enhancements, explain the problem or goal, the desired outcome, and clear acceptance criteria. +- For UI issues, include screenshots. Include a short video when motion or interaction is relevant. +- Link any related issues and pull requests. +- Apply the appropriate existing labels when creating an issue: `bug` for bugs, `enhancement` for feature requests, and any applicable platform labels (`macOS`, `iOS`, `iPadOS`). + ## What Agents Should Avoid - No UIKit/AppKit imports. @@ -46,8 +70,6 @@ When in doubt, choose the simplest modern SwiftUI-first solution. ## Build Workflow -This command builds the macOS destination only. - From repo root (`/Users/austinsmith/Developer/Repos/ComputerSolitaire`), run: ```bash @@ -59,6 +81,19 @@ From repo root (`/Users/austinsmith/Developer/Repos/ComputerSolitaire`), run: build ``` +For an iOS Simulator compile check without signing, run: + +```bash +/Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild \ + -project ComputerSolitaire.xcodeproj \ + -scheme ComputerSolitaire \ + -configuration Debug \ + -destination 'generic/platform=iOS Simulator' \ + CODE_SIGNING_ALLOWED=NO \ + CODE_SIGNING_REQUIRED=NO \ + build +``` + ## Test Workflow From repo root (`/Users/austinsmith/Developer/Repos/ComputerSolitaire`), run: @@ -69,5 +104,13 @@ From repo root (`/Users/austinsmith/Developer/Repos/ComputerSolitaire`), run: -scheme ComputerSolitaire \ -configuration Debug \ -destination 'platform=macOS' \ + CODE_SIGNING_ALLOWED=NO \ + CODE_SIGNING_REQUIRED=NO \ test ``` + +Testing guidance: + +- Add tests when they protect game rules, persistence, scoring, solver behavior, meaningful user-visible behavior, cross-file integration, bug regressions, or non-trivial logic that is easy to break. +- Do not add dedicated tests for every small helper extraction, straightforward computed property, or internal refactor unless the change introduces real behavioral risk. +- Prefer a small number of high-signal tests over many narrow tests that only restate the implementation. From 90073f9da1d3dff72a9b6adb2a719938e17b1c82 Mon Sep 17 00:00:00 2001 From: Austin Smith Date: Sat, 11 Jul 2026 16:48:45 -0700 Subject: [PATCH 2/2] narrow contribution templates to bitdream setup --- .github/ISSUE_TEMPLATE/bug_report.yml | 36 ++------------------------- .github/pull_request_template.md | 2 +- AGENTS.md | 25 +++---------------- 3 files changed, 6 insertions(+), 57 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 1b7f8a7..54593e8 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -20,50 +20,18 @@ body: id: reproduction attributes: label: Steps to reproduce - description: Provide the smallest reliable reproduction you have. If the problem is intermittent, explain when it occurs. + description: Provide the smallest reliable reproduction you have. placeholder: | 1. 2. 3. - validations: - required: true - - - type: dropdown - id: platform - attributes: - label: Platform - options: - - macOS - - iPhone - - iPad - validations: - required: true - type: input id: environment attributes: label: Environment - description: Include the OS version and Computer Solitaire version when known. + description: Include the platform, OS version, and Computer Solitaire version when known. placeholder: macOS 26.2, Computer Solitaire 1.0 - validations: - required: true - - - type: dropdown - id: game - attributes: - label: Game variant - options: - - Klondike - - FreeCell - - Not game-specific - validations: - required: true - - - type: textarea - id: game-context - attributes: - label: Game settings or context - description: Include relevant settings such as draw mode or scoring mode, and describe the state of the game when the problem occurred. - type: textarea id: evidence diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ecb8e69..4d0d7ca 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,5 +14,5 @@ ## Validation - diff --git a/AGENTS.md b/AGENTS.md index 97584ca..9994610 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,7 +53,7 @@ This file defines hard project constraints for any coding agent working in this - Keep each issue focused on one problem or change. - Use a concise, specific, sentence-case title without type prefixes. - Give enough context to understand the issue without first inspecting the code. -- For bugs, describe the current and expected behavior. Include reproduction steps, environment details, the game variant and relevant settings, and supporting evidence when available. +- For bugs, describe the current and expected behavior. Include reproduction steps, environment details, and supporting evidence when available. - For enhancements, explain the problem or goal, the desired outcome, and clear acceptance criteria. - For UI issues, include screenshots. Include a short video when motion or interaction is relevant. - Link any related issues and pull requests. @@ -70,6 +70,8 @@ When in doubt, choose the simplest modern SwiftUI-first solution. ## Build Workflow +This command builds the macOS destination only. + From repo root (`/Users/austinsmith/Developer/Repos/ComputerSolitaire`), run: ```bash @@ -81,19 +83,6 @@ From repo root (`/Users/austinsmith/Developer/Repos/ComputerSolitaire`), run: build ``` -For an iOS Simulator compile check without signing, run: - -```bash -/Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild \ - -project ComputerSolitaire.xcodeproj \ - -scheme ComputerSolitaire \ - -configuration Debug \ - -destination 'generic/platform=iOS Simulator' \ - CODE_SIGNING_ALLOWED=NO \ - CODE_SIGNING_REQUIRED=NO \ - build -``` - ## Test Workflow From repo root (`/Users/austinsmith/Developer/Repos/ComputerSolitaire`), run: @@ -104,13 +93,5 @@ From repo root (`/Users/austinsmith/Developer/Repos/ComputerSolitaire`), run: -scheme ComputerSolitaire \ -configuration Debug \ -destination 'platform=macOS' \ - CODE_SIGNING_ALLOWED=NO \ - CODE_SIGNING_REQUIRED=NO \ test ``` - -Testing guidance: - -- Add tests when they protect game rules, persistence, scoring, solver behavior, meaningful user-visible behavior, cross-file integration, bug regressions, or non-trivial logic that is easy to break. -- Do not add dedicated tests for every small helper extraction, straightforward computed property, or internal refactor unless the change introduces real behavioral risk. -- Prefer a small number of high-signal tests over many narrow tests that only restate the implementation.