From b1a59ce530371fd4892feb0fe3d3176a26271591 Mon Sep 17 00:00:00 2001 From: charlieroth Date: Sat, 23 Aug 2025 12:16:09 +0200 Subject: [PATCH] feat: implement repository hygiene (#18) - Add CODEOWNERS file with ownership rules - Add MIT LICENSE with 2024 copyright - Add CONTRIBUTING.md with development workflow and guidelines - Add SECURITY.md with vulnerability reporting process - Add GitHub issue templates for bug reports, feature requests, and tasks - Add comprehensive Pull Request template with checklist Closes #18 Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-67d5d6d9-ed95-45c4-ad58-c3146da224e4 --- .github/CODEOWNERS | 20 ++++ .github/ISSUE_TEMPLATE/bug_report.yml | 98 ++++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 95 +++++++++++++++ .github/ISSUE_TEMPLATE/task.yml | 128 +++++++++++++++++++++ .github/pull_request_template.md | 87 ++++++++++++++ CONTRIBUTING.md | 111 ++++++++++++++++++ LICENSE | 21 ++++ SECURITY.md | 85 ++++++++++++++ 8 files changed, 645 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/task.yml create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 SECURITY.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..85ff9b2 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,20 @@ +# Global owners +* @charlieroth + +# Rust code +*.rs @charlieroth +Cargo.toml @charlieroth +Cargo.lock @charlieroth + +# Database migrations +migrations/ @charlieroth + +# Documentation +*.md @charlieroth +docs/ @charlieroth + +# CI/CD +.github/ @charlieroth +Dockerfile @charlieroth +docker-compose.yml @charlieroth +Makefile @charlieroth diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..c8bd435 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,98 @@ +name: Bug Report +description: File a bug report to help us improve +title: "[BUG] " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: A clear and concise description of what the bug is. + placeholder: Tell us what you see! + validations: + required: true + + - type: textarea + id: steps-to-reproduce + attributes: + label: Steps to Reproduce + description: Steps to reproduce the behavior + placeholder: | + 1. Go to '...' + 2. Click on '....' + 3. Scroll down to '....' + 4. See error + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: Expected Behavior + description: A clear and concise description of what you expected to happen. + validations: + required: true + + - type: textarea + id: actual-behavior + attributes: + label: Actual Behavior + description: A clear and concise description of what actually happened. + validations: + required: true + + - type: dropdown + id: severity + attributes: + label: Severity + description: How severe is this bug? + options: + - Critical (system unusable) + - High (major functionality broken) + - Medium (some functionality affected) + - Low (minor issue) + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: | + Please provide relevant environment information + value: | + - OS: [e.g. macOS 14.0, Ubuntu 22.04] + - Rust version: [e.g. 1.75.0] + - Database: [e.g. PostgreSQL 15.4] + render: markdown + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs + description: Please copy and paste relevant log output. This will be automatically formatted into code. + render: shell + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context about the problem here. + + - type: checkboxes + id: terms + attributes: + label: Checklist + description: By submitting this issue, you agree to follow our Code of Conduct + options: + - label: I have searched existing issues to ensure this is not a duplicate + required: true + - label: I have provided all the required information + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..76045e0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,95 @@ +name: Feature Request +description: Suggest an idea or enhancement for Capsule +title: "[FEATURE] " +labels: ["enhancement", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to suggest a feature! + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: Is your feature request related to a problem? Please describe the problem you're trying to solve. + placeholder: I'm always frustrated when... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like to see implemented. + placeholder: I would like to see... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternative Solutions + description: Describe any alternative solutions or features you've considered. + placeholder: Alternatively, we could... + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - Critical (blocking current work) + - High (would significantly improve workflow) + - Medium (nice to have) + - Low (minor improvement) + validations: + required: true + + - type: dropdown + id: complexity + attributes: + label: Estimated Complexity + description: How complex do you think this feature would be to implement? + options: + - Simple (small change, few files affected) + - Medium (moderate change, multiple components) + - Complex (large change, significant architecture impact) + - Unknown + + - type: textarea + id: use-cases + attributes: + label: Use Cases + description: Describe specific use cases where this feature would be helpful. + placeholder: | + 1. When doing X, this feature would help by... + 2. In scenario Y, this would solve... + + - type: textarea + id: acceptance-criteria + attributes: + label: Acceptance Criteria + description: What would need to be true for this feature to be considered complete? + placeholder: | + - [ ] Feature does X + - [ ] Feature handles edge case Y + - [ ] Documentation is updated + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context, screenshots, mockups, or examples about the feature request. + + - type: checkboxes + id: terms + attributes: + label: Checklist + options: + - label: I have searched existing issues to ensure this is not a duplicate + required: true + - label: I have provided a clear problem statement and proposed solution + required: true + - label: This feature aligns with the project's goals and scope + required: true diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml new file mode 100644 index 0000000..be86568 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/task.yml @@ -0,0 +1,128 @@ +name: Task +description: Create a task or work item +title: "[TASK] " +labels: ["task", "triage"] +body: + - type: markdown + attributes: + value: | + Use this template to create development tasks, maintenance work, or other project activities. + + - type: textarea + id: description + attributes: + label: Task Description + description: Clearly describe what needs to be done. + placeholder: Describe the task that needs to be completed... + validations: + required: true + + - type: textarea + id: why + attributes: + label: Why + description: Explain why this task is necessary or beneficial. + placeholder: This task is needed because... + validations: + required: true + + - type: textarea + id: definition-of-done + attributes: + label: Definition of Done + description: What criteria must be met for this task to be considered complete? + placeholder: | + - [ ] Specific deliverable 1 + - [ ] Specific deliverable 2 + - [ ] Tests written/updated + - [ ] Documentation updated + validations: + required: true + + - type: dropdown + id: type + attributes: + label: Task Type + description: What type of task is this? + options: + - Development (new feature/functionality) + - Refactoring (code improvement) + - Maintenance (updates, cleanup) + - Documentation (docs, README, etc.) + - Infrastructure (CI/CD, deployment) + - Testing (add/improve tests) + - Research (investigation, exploration) + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Priority + description: How urgent is this task? + options: + - Critical (must be done immediately) + - High (should be done soon) + - Medium (normal priority) + - Low (can be done later) + validations: + required: true + + - type: dropdown + id: effort + attributes: + label: Estimated Effort + description: How much work do you think this will require? + options: + - XS (< 1 hour) + - S (1-4 hours) + - M (4-8 hours) + - L (1-2 days) + - XL (2+ days) + - Unknown + + - type: textarea + id: tasks + attributes: + label: Sub-tasks + description: Break down the work into smaller, actionable items. + placeholder: | + - [ ] Task 1 + - [ ] Task 2 + - [ ] Task 3 + + - type: textarea + id: dependencies + attributes: + label: Dependencies + description: Are there any other issues, PRs, or external dependencies that must be completed first? + placeholder: | + - Depends on #123 + - Requires external library X to be updated + + - type: textarea + id: acceptance-criteria + attributes: + label: Acceptance Criteria + description: Specific, testable conditions that must be satisfied. + placeholder: | + - Given [context], when [action], then [expected result] + - System should handle [scenario] correctly + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Any other relevant information, links, or context. + + - type: checkboxes + id: terms + attributes: + label: Checklist + options: + - label: I have provided a clear description and definition of done + required: true + - label: I have checked for similar existing tasks + required: true + - label: This task is appropriately scoped (not too large) + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..13df9c8 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,87 @@ +## Summary + +Brief description of what this PR accomplishes. + +Fixes #(issue number) + +## Changes Made + +- [ ] Feature/functionality changes +- [ ] Bug fixes +- [ ] Refactoring +- [ ] Documentation updates +- [ ] Test additions/improvements +- [ ] Infrastructure/CI changes + +### Detailed Changes + +- Change 1: Description +- Change 2: Description +- Change 3: Description + +## Testing + +- [ ] All existing tests pass (`make test`) +- [ ] New tests added for new functionality +- [ ] Manual testing completed +- [ ] Edge cases considered and tested + +### Test Commands Run +```bash +# List the specific test commands you ran +make test +cargo test specific_test_name +``` + +## Code Quality + +- [ ] Code follows project style guidelines (`make fmt`) +- [ ] No linting errors (`make lint`) +- [ ] Full check passes (`make check`) +- [ ] Code is well-documented where necessary +- [ ] No security vulnerabilities introduced + +## Database Changes + +- [ ] No database changes +- [ ] Migration scripts included +- [ ] `make prepare` run after schema changes +- [ ] Backward compatibility maintained + +## Breaking Changes + +- [ ] No breaking changes +- [ ] Breaking changes documented below + +### Breaking Changes Details + + +## Deployment Notes + +- [ ] No special deployment considerations +- [ ] Environment variables need to be updated +- [ ] Dependencies need to be updated +- [ ] Special deployment steps required (documented below) + +### Special Deployment Steps + + +## Documentation + +- [ ] No documentation changes needed +- [ ] README updated +- [ ] API documentation updated +- [ ] Contributing guidelines updated +- [ ] Other documentation updated (specify below) + +## Reviewer Checklist + +- [ ] Code review completed +- [ ] Architecture/design approved +- [ ] Security considerations reviewed +- [ ] Performance impact assessed +- [ ] Documentation reviewed + +## Additional Notes + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3e2a9f2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,111 @@ +# Contributing to Capsule + +Thank you for your interest in contributing to Capsule! This document provides guidelines for contributing to the project. + +## Development Setup + +### Prerequisites +- Rust (latest stable version) +- Docker and Docker Compose +- PostgreSQL client tools (optional) + +### Getting Started + +1. Clone the repository: + ```bash + git clone https://github.com/charlieroth/capsule.git + cd capsule + ``` + +2. Set up environment variables: + ```bash + cp .envrc.template .envrc + # Edit .envrc with your configuration + source .envrc # or use direnv + ``` + +3. Start the database: + ```bash + make db-up + make db-migrate + ``` + +4. Build and run: + ```bash + make dev + ``` + +## Development Workflow + +### Before Making Changes + +1. Ensure all tests pass: `make test` +2. Check code formatting: `make fmt` +3. Run linter: `make lint` +4. Full check: `make check` + +### Making Changes + +1. Create a feature branch: `git checkout -b feature/your-feature` +2. Make your changes following the code style guidelines below +3. Add tests for new functionality +4. Update documentation as needed +5. Run the full check: `make check` + +### Submitting Changes + +1. Push your branch: `git push origin feature/your-feature` +2. Create a Pull Request +3. Fill out the PR template completely +4. Ensure CI checks pass +5. Address any review feedback + +## Code Style Guidelines + +### Rust Code +- Use `rustfmt` for formatting: `make fmt` +- Follow clippy recommendations: `make lint` +- Use meaningful variable and function names +- Add docstrings for public APIs +- Use strong typing with custom domain types + +### Testing +- Write tests for new functionality +- Use `#[cfg(test)] mod tests` within source files +- Follow naming convention: `test__` +- Mock external dependencies appropriately + +### Database +- Use SQLx with compile-time checked queries +- Run `make prepare` after schema changes +- Create migrations for all schema changes +- Document migration purpose in filename + +### Imports Organization +```rust +// Standard library +use std::collections::HashMap; + +// External crates +use axum::Router; +use sqlx::PgPool; + +// Local modules +use crate::entities::User; +``` + +## Security + +- Never commit secrets or API keys +- Use proper JWT handling for authentication +- Follow secure coding practices +- Report security issues via email (see SECURITY.md) + +## Questions? + +If you have questions about contributing, please: +1. Check existing issues and discussions +2. Open a new issue with the "question" label +3. Reach out to maintainers + +Thank you for contributing! diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9531801 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Charlie Roth + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..60aa2ce --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,85 @@ +# Security Policy + +## Supported Versions + +Security updates are provided for the following versions: + +| Version | Supported | +| ------- | ------------------ | +| main | :white_check_mark: | + +## Reporting a Vulnerability + +If you discover a security vulnerability in Capsule, please report it responsibly: + +### Private Disclosure + +**DO NOT** create a public GitHub issue for security vulnerabilities. + +Instead, please report security issues via email to: **charlie@charlieroth.com** + +### Information to Include + +When reporting a vulnerability, please include: + +1. **Description**: A clear description of the vulnerability +2. **Steps to Reproduce**: Detailed steps to reproduce the issue +3. **Impact**: Description of the potential impact +4. **Affected Components**: Which parts of the system are affected +5. **Suggested Fix**: If you have ideas for a fix (optional) + +### What to Expect + +1. **Acknowledgment**: We'll acknowledge receipt within 48 hours +2. **Assessment**: Initial assessment within 5 business days +3. **Updates**: Regular updates on investigation progress +4. **Resolution**: Coordinated fix and disclosure timeline + +### Responsible Disclosure + +We follow responsible disclosure practices: + +- We'll work with you to understand and resolve the issue +- We'll provide credit for the discovery (if desired) +- We'll coordinate public disclosure after a fix is available +- We'll notify affected users appropriately + +## Security Best Practices + +When contributing to Capsule: + +### Code Security +- Never commit secrets, API keys, or credentials +- Use secure coding practices for authentication and authorization +- Validate all user inputs +- Follow OWASP guidelines for web application security + +### Database Security +- Use parameterized queries to prevent SQL injection +- Apply principle of least privilege for database access +- Encrypt sensitive data at rest and in transit + +### Infrastructure Security +- Keep dependencies up to date +- Use secure communication channels (HTTPS/TLS) +- Follow container security best practices + +## Security Features + +Capsule implements the following security measures: + +- JWT-based authentication +- Argon2 password hashing +- SQL injection prevention through SQLx +- Input validation and sanitization +- Secure session management + +## Vulnerability Disclosure Timeline + +We aim to: +- Acknowledge reports within 48 hours +- Provide initial assessment within 5 business days +- Release fixes within 30 days for critical vulnerabilities +- Release fixes within 90 days for non-critical vulnerabilities + +Thank you for helping keep Capsule secure!