From 34e0ea81c2801fe6fdb3b1d392df6513854dfbbc Mon Sep 17 00:00:00 2001
From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com>
Date: Sat, 19 Sep 2026 09:39:15 +0000
Subject: [PATCH] refactor(root): relocate the contributing guide into .github/

The estate canonical location is .github/CONTRIBUTING.md, which GitHub
auto-discovers; the root copy is removed and references are updated in the same
change.

  * .github/CONTRIBUTING.md
      (new)
  * CONTRIBUTING.adoc
      (deleted)
  * Justfile
  * README.adoc
  * REVERSIBILITY.adoc
  * bootstrap.sh
---
 .github/CONTRIBUTING.md | 304 ++++++++++++++++++++++++++++++++++++++++
 CONTRIBUTING.adoc       | 248 --------------------------------
 Justfile                |   2 +-
 README.adoc             |   2 +-
 REVERSIBILITY.adoc      |   2 +-
 bootstrap.sh            |   2 +-
 6 files changed, 308 insertions(+), 252 deletions(-)
 create mode 100644 .github/CONTRIBUTING.md
 delete mode 100644 CONTRIBUTING.adoc

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 0000000..86b34c5
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,304 @@
+# Contributing to Candy Crash
+
+Thank you for your interest in contributing to Candy Crash! This
+document provides guidelines for contributing to the project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+
+- [Getting Started](#getting-started)
+
+- [Development Workflow](#development-workflow)
+
+- [Coding Standards](#coding-standards)
+
+- [Testing Requirements](#testing-requirements)
+
+- [Commit Guidelines](#commit-guidelines)
+
+- [Pull Request Process](#pull-request-process)
+
+- [Security Vulnerabilities](#security-vulnerabilities)
+
+## Code of Conduct
+
+This project adheres to a Code of Conduct that all contributors are
+expected to follow. Please read
+<a href="CODE_OF_CONDUCT.adoc" class="adoc">CODE_OF_CONDUCT</a> before
+contributing.
+
+## Getting Started
+
+### Prerequisites
+
+- Ruby 3.3.6
+
+- Rails 7.1.3
+
+- SQLite3
+
+- Node.js (for asset compilation)
+
+- Git
+
+### Setup Development Environment
+
+``` bash
+# Clone the repository
+git clone https://github.com/Hyperpolymath/candy-crash.git
+cd candy-crash
+
+# Install dependencies
+bundle install
+
+# Setup database
+rails db:create db:migrate db:seed
+
+# Run tests
+rspec
+
+# Start development server
+rails server
+```
+
+## Development Workflow
+
+1.  **Fork the repository** and create your branch from `main`
+
+2.  **Make your changes** following our coding standards
+
+3.  **Write tests** for new functionality
+
+4.  **Update documentation** as needed
+
+5.  **Run the test suite** and ensure all tests pass
+
+6.  **Submit a pull request**
+
+### Branch Naming Convention
+
+- `feature/description` - New features
+
+- `fix/description` - Bug fixes
+
+- `docs/description` - Documentation updates
+
+- `refactor/description` - Code refactoring
+
+- `test/description` - Test additions/improvements
+
+## Coding Standards
+
+### Ruby Style Guide
+
+We follow the [Ruby Style Guide](https://rubystyle.guide/) with these
+conventions:
+
+- **Indentation**: 2 spaces (no tabs)
+
+- **Line length**: 120 characters maximum
+
+- **Method length**: Keep methods under 10 lines when possible
+
+- **Class length**: Keep classes focused and under 100 lines
+
+### Rails Conventions
+
+- Keep controllers thin, models fat
+
+- Use service objects for complex business logic
+
+- Follow RESTful routing conventions
+
+- Use strong parameters for security
+
+- Write self-documenting code with clear naming
+
+### Code Quality Tools
+
+``` bash
+# Run RuboCop for style checking
+rubocop
+
+# Auto-fix violations
+rubocop -a
+
+# Run Brakeman for security analysis
+brakeman
+
+# Check for vulnerable dependencies
+bundle audit check
+```
+
+## Testing Requirements
+
+### Test Coverage
+
+- All new features must include tests
+
+- Bug fixes should include regression tests
+
+- Aim for \>80% code coverage
+
+- Test both happy paths and error cases
+
+### Running Tests
+
+``` bash
+# Run all tests
+rspec
+
+# Run specific test file
+rspec spec/models/user_spec.rb
+
+# Run with coverage report
+COVERAGE=true rspec
+```
+
+### Test Structure
+
+- **Unit tests**: Test individual methods and classes
+
+- **Integration tests**: Test component interactions
+
+- **Request tests**: Test HTTP endpoints
+
+- **System tests**: Test user workflows (optional)
+
+## Commit Guidelines
+
+### Commit Message Format
+
+    <type>(<scope>): <subject>
+
+    <body>
+
+    <footer>
+
+**Types:**
+
+- `feat`: New feature
+
+- `fix`: Bug fix
+
+- `docs`: Documentation only
+
+- `style`: Formatting, missing semicolons, etc.
+
+- `refactor`: Code restructuring
+
+- `test`: Adding tests
+
+- `chore`: Maintenance tasks
+
+**Example:**
+
+    feat(courses): Add course search functionality
+
+    Implement ransack-based search allowing users to filter
+    courses by title, category, and difficulty level.
+
+    Closes #123
+
+### Commit Best Practices
+
+- Use present tense ("Add feature" not "Added feature")
+
+- Use imperative mood ("Move cursor to…" not "Moves cursor to…")
+
+- First line max 50 characters
+
+- Body wrapped at 72 characters
+
+- Reference issues and PRs when relevant
+
+## Pull Request Process
+
+### Before Submitting
+
+- [ ] All tests pass (`rspec`)
+
+- [ ] Code passes linting (`rubocop`)
+
+- [ ] Security scan passes (`brakeman`)
+
+- [ ] Documentation updated
+
+- [ ] CHANGELOG.adoc updated (for significant changes)
+
+- [ ] Database migrations tested both up and down
+
+### PR Template
+
+    ## Description
+    Brief description of changes
+
+    ## Type of Change
+    - [ ] Bug fix
+    - [ ] New feature
+    - [ ] Breaking change
+    - [ ] Documentation update
+
+    ## Testing
+    How has this been tested?
+
+    ## Checklist
+    - [ ] Tests pass
+    - [ ] Code follows style guidelines
+    - [ ] Self-review completed
+    - [ ] Documentation updated
+
+### Review Process
+
+1.  **Automated checks** must pass (CI/CD pipeline)
+
+2.  **At least one maintainer** must approve
+
+3.  **Security review** required for auth/authorization changes
+
+4.  **Performance impact** assessed for database/query changes
+
+### Merge Strategy
+
+- We use **squash and merge** for feature branches
+
+- Maintain **linear history** on main branch
+
+- Delete branch after merge
+
+## Security Vulnerabilities
+
+**Never** report security issues via public GitHub issues.
+
+See <a href="SECURITY.md" class="md">SECURITY</a> for responsible
+disclosure procedures.
+
+## Recognition
+
+Contributors are recognized in:
+
+- Git commit history
+
+- CHANGELOG.adoc for significant contributions
+
+- README.adoc contributors section (optional)
+
+- Annual contributor appreciation (if applicable)
+
+## Questions?
+
+- Open a **Discussion** for general questions
+
+- **Issue tracker** for bugs and feature requests
+
+- Contact maintainers (see MAINTAINERS.adoc)
+
+## License
+
+By contributing, you agree that your contributions will be licensed
+under the same license as the project (see LICENSE file).
+
+------------------------------------------------------------------------
+
+Thank you for making Candy Crash better! 🚗📚
diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
deleted file mode 100644
index 939cbcd..0000000
--- a/CONTRIBUTING.adoc
+++ /dev/null
@@ -1,248 +0,0 @@
-= Contributing to Candy Crash
-
-Thank you for your interest in contributing to Candy Crash! This document provides guidelines for contributing to the project.
-
-== Table of Contents
-
-* link:#code-of-conduct[Code of Conduct]
-* link:#getting-started[Getting Started]
-* link:#development-workflow[Development Workflow]
-* link:#coding-standards[Coding Standards]
-* link:#testing-requirements[Testing Requirements]
-* link:#commit-guidelines[Commit Guidelines]
-* link:#pull-request-process[Pull Request Process]
-* link:#security-vulnerabilities[Security Vulnerabilities]
-
-== Code of Conduct
-
-This project adheres to a Code of Conduct that all contributors are expected to follow. Please read link:CODE_OF_CONDUCT.adoc[CODE_OF_CONDUCT.adoc] before contributing.
-
-== Getting Started
-
-=== Prerequisites
-
-* Ruby 3.3.6
-* Rails 7.1.3
-* SQLite3
-* Node.js (for asset compilation)
-* Git
-
-=== Setup Development Environment
-
-[source,bash]
-----
-# Clone the repository
-git clone https://github.com/Hyperpolymath/candy-crash.git
-cd candy-crash
-
-# Install dependencies
-bundle install
-
-# Setup database
-rails db:create db:migrate db:seed
-
-# Run tests
-rspec
-
-# Start development server
-rails server
-----
-
-== Development Workflow
-
-. *Fork the repository* and create your branch from `main`
-. *Make your changes* following our coding standards
-. *Write tests* for new functionality
-. *Update documentation* as needed
-. *Run the test suite* and ensure all tests pass
-. *Submit a pull request*
-
-=== Branch Naming Convention
-
-* `feature/description` - New features
-* `fix/description` - Bug fixes
-* `docs/description` - Documentation updates
-* `refactor/description` - Code refactoring
-* `test/description` - Test additions/improvements
-
-== Coding Standards
-
-=== Ruby Style Guide
-
-We follow the link:https://rubystyle.guide/[Ruby Style Guide] with these conventions:
-
-* *Indentation*: 2 spaces (no tabs)
-* *Line length*: 120 characters maximum
-* *Method length*: Keep methods under 10 lines when possible
-* *Class length*: Keep classes focused and under 100 lines
-
-=== Rails Conventions
-
-* Keep controllers thin, models fat
-* Use service objects for complex business logic
-* Follow RESTful routing conventions
-* Use strong parameters for security
-* Write self-documenting code with clear naming
-
-=== Code Quality Tools
-
-[source,bash]
-----
-# Run RuboCop for style checking
-rubocop
-
-# Auto-fix violations
-rubocop -a
-
-# Run Brakeman for security analysis
-brakeman
-
-# Check for vulnerable dependencies
-bundle audit check
-----
-
-== Testing Requirements
-
-=== Test Coverage
-
-* All new features must include tests
-* Bug fixes should include regression tests
-* Aim for >80% code coverage
-* Test both happy paths and error cases
-
-=== Running Tests
-
-[source,bash]
-----
-# Run all tests
-rspec
-
-# Run specific test file
-rspec spec/models/user_spec.rb
-
-# Run with coverage report
-COVERAGE=true rspec
-----
-
-=== Test Structure
-
-* *Unit tests*: Test individual methods and classes
-* *Integration tests*: Test component interactions
-* *Request tests*: Test HTTP endpoints
-* *System tests*: Test user workflows (optional)
-
-== Commit Guidelines
-
-=== Commit Message Format
-
-----
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-----
-
-*Types:*
-
-* `feat`: New feature
-* `fix`: Bug fix
-* `docs`: Documentation only
-* `style`: Formatting, missing semicolons, etc.
-* `refactor`: Code restructuring
-* `test`: Adding tests
-* `chore`: Maintenance tasks
-
-*Example:*
-
-----
-feat(courses): Add course search functionality
-
-Implement ransack-based search allowing users to filter
-courses by title, category, and difficulty level.
-
-Closes #123
-----
-
-=== Commit Best Practices
-
-* Use present tense ("Add feature" not "Added feature")
-* Use imperative mood ("Move cursor to..." not "Moves cursor to...")
-* First line max 50 characters
-* Body wrapped at 72 characters
-* Reference issues and PRs when relevant
-
-== Pull Request Process
-
-=== Before Submitting
-
-* [ ] All tests pass (`rspec`)
-* [ ] Code passes linting (`rubocop`)
-* [ ] Security scan passes (`brakeman`)
-* [ ] Documentation updated
-* [ ] CHANGELOG.adoc updated (for significant changes)
-* [ ] Database migrations tested both up and down
-
-=== PR Template
-
-----
-## Description
-Brief description of changes
-
-## Type of Change
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Breaking change
-- [ ] Documentation update
-
-## Testing
-How has this been tested?
-
-## Checklist
-- [ ] Tests pass
-- [ ] Code follows style guidelines
-- [ ] Self-review completed
-- [ ] Documentation updated
-----
-
-=== Review Process
-
-. *Automated checks* must pass (CI/CD pipeline)
-. *At least one maintainer* must approve
-. *Security review* required for auth/authorization changes
-. *Performance impact* assessed for database/query changes
-
-=== Merge Strategy
-
-* We use *squash and merge* for feature branches
-* Maintain *linear history* on main branch
-* Delete branch after merge
-
-== Security Vulnerabilities
-
-*Never* report security issues via public GitHub issues.
-
-See link:SECURITY.md[SECURITY.md] for responsible disclosure procedures.
-
-== Recognition
-
-Contributors are recognized in:
-
-* Git commit history
-* CHANGELOG.adoc for significant contributions
-* README.adoc contributors section (optional)
-* Annual contributor appreciation (if applicable)
-
-== Questions?
-
-* Open a *Discussion* for general questions
-* *Issue tracker* for bugs and feature requests
-* Contact maintainers (see MAINTAINERS.adoc)
-
-== License
-
-By contributing, you agree that your contributions will be licensed under the same license as the project (see LICENSE file).
-
----
-
-Thank you for making Candy Crash better! 🚗📚
diff --git a/Justfile b/Justfile
index 857f4b7..562249e 100644
--- a/Justfile
+++ b/Justfile
@@ -92,7 +92,7 @@ validate-rsr:
     @test -f README.adoc && echo "  ✓ README.adoc" || echo "  ✗ README.adoc missing"
     @test -f LICENSE && echo "  ✓ LICENSE" || echo "  ✗ LICENSE missing"
     @test -f SECURITY.md && echo "  ✓ SECURITY.md" || echo "  ✗ SECURITY.md missing"
-    @test -f CONTRIBUTING.adoc && echo "  ✓ CONTRIBUTING.adoc" || echo "  ✗ CONTRIBUTING.adoc missing"
+    @test -f .github/CONTRIBUTING.md && echo "  ✓ .github/CONTRIBUTING.md" || echo "  ✗ .github/CONTRIBUTING.md missing"
     @test -f CODE_OF_CONDUCT.adoc && echo "  ✓ CODE_OF_CONDUCT.adoc" || echo "  ✗ CODE_OF_CONDUCT.adoc missing"
     @test -f MAINTAINERS.adoc && echo "  ✓ MAINTAINERS.adoc" || echo "  ✗ MAINTAINERS.adoc missing"
     @test -f CHANGELOG.adoc && echo "  ✓ CHANGELOG.adoc" || echo "  ✗ CHANGELOG.adoc missing"
diff --git a/README.adoc b/README.adoc
index 73e823b..8da8691 100644
--- a/README.adoc
+++ b/README.adoc
@@ -461,7 +461,7 @@ This project requires contributors who understand:
 * The specific vehicle domains being addressed
 * Privacy-preserving system design
 
-See link:./CONTRIBUTING.adoc[CONTRIBUTING.adoc].
+See link:./.github/CONTRIBUTING.md[.github/CONTRIBUTING.md].
 
 == License
 
diff --git a/REVERSIBILITY.adoc b/REVERSIBILITY.adoc
index 8818fbe..69a374d 100644
--- a/REVERSIBILITY.adoc
+++ b/REVERSIBILITY.adoc
@@ -345,4 +345,4 @@ rails db:migrate  # Must succeed
 
 == Questions?
 
-See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for how to ask questions or propose improvements to reversibility features.
+See link:.github/CONTRIBUTING.md[.github/CONTRIBUTING.md] for how to ask questions or propose improvements to reversibility features.
diff --git a/bootstrap.sh b/bootstrap.sh
index a8d3510..5c32252 100755
--- a/bootstrap.sh
+++ b/bootstrap.sh
@@ -209,7 +209,7 @@ echo ""
 echo -e "${GREEN}✅ Bootstrap complete!${NC}"
 echo ""
 echo "Next steps:"
-echo "  1. Review CONTRIBUTING.adoc for contribution guidelines"
+echo "  1. Review .github/CONTRIBUTING.md for contribution guidelines"
 echo "  2. Read CLAUDE.adoc for AI assistant instructions"
 echo "  3. Run 'just --list' to see available commands"
 echo "  4. Start development server: 'just serve'"