diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ff18cbd..b410961 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,24 +1,36 @@ -# Pull Request +## Summary -## Description + -Describe the changes made in this pull request. +## Linked issue -## Type of Change + -- [ ] Bug fix -- [ ] New feature -- [ ] Documentation update -- [ ] Refactoring -- [ ] Other +Closes # -## Testing +## Why this change -Describe how you tested these changes. + + +## Compatibility and safety + + + +## Validation + + + +```text +ruff check . +ruff format --check . +pytest +``` ## Checklist -- [ ] My code follows the project style. -- [ ] I have tested my changes. -- [ ] I have updated the documentation if needed. -- [ ] All tests pass. \ No newline at end of file +- [ ] This PR is focused on one issue and contains no unrelated changes. +- [ ] I added or updated tests for behavior changes, or explained why tests are not needed. +- [ ] I updated user or contributor documentation when needed. +- [ ] I considered backward compatibility and filesystem safety where applicable. +- [ ] I ran the relevant local checks and included the results above. +- [ ] I did not include secrets, local environments, build output, or real user files. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c417bbf..aeac5f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,17 +1,69 @@ # Contributing -Thank you for considering a contribution to Creator Toolkit CLI. +Thank you for helping make Creator Toolkit CLI safer and more useful for creator workflows. +Focused bug fixes, documentation improvements, tests, and small features are welcome. -1. Fork the repository and create a focused branch. -2. Create a virtual environment and install the development tools: +## Find work and signal your intent + +- Start with an open + [`good first issue`](https://github.com/HoungDev/creator-toolkit-cli/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) + or [`help wanted`](https://github.com/HoungDev/creator-toolkit-cli/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22) + issue. +- Comment with the approach you plan to take before investing significant time. This helps avoid + duplicate work and gives maintainers a chance to clarify edge cases. +- Keep the pull request focused on one issue. Propose larger or unrelated behavior separately + through the [issue chooser](https://github.com/HoungDev/creator-toolkit-cli/issues/new/choose). +- Report vulnerabilities through + [private vulnerability reporting](https://github.com/HoungDev/creator-toolkit-cli/security/advisories/new), + not a public issue. + +## Set up the project + +Fork the repository, clone your fork, and create a descriptive branch: + +```bash +git clone https://github.com/YOUR-USERNAME/creator-toolkit-cli.git +cd creator-toolkit-cli +git switch -c fix/short-description +``` + +Create and activate a virtual environment: ```bash python -m venv .venv +``` + +PowerShell: + +```powershell +.\.venv\Scripts\Activate.ps1 +``` + +macOS or Linux: + +```bash +source .venv/bin/activate +``` + +Install the project and development tools, then verify the CLI is available: + +```bash +python -m pip install --upgrade pip python -m pip install -e ".[dev]" +creator-toolkit --help ``` -3. Make your changes and add tests for new behavior. -4. Run the same quality checks used in CI: +Install `.[dev,demo]` instead when changing the generated README demo. + +## Make a focused change + +- Add or update tests for behavior changes and regressions. +- Preserve documented CLI, JSON, manifest, and exit-code compatibility unless the issue explicitly + calls for a breaking change. +- Update user-facing documentation when flags, output, or workflows change. +- Do not commit credentials, tokens, local environments, build output, or real user files. + +Run focused tests while developing, then run the full local quality suite: ```bash ruff check . @@ -21,7 +73,27 @@ python -m build python -m twine check dist/* ``` -5. Commit and push your branch, then open a pull request. +If the README demo changes, rebuild its tracked asset from real CLI output: + +```bash +python scripts/render_readme_demo.py +``` + +CI repeats the quality suite on Python 3.11–3.13 and smoke-tests the installed command on Windows, +macOS, and Ubuntu. + +## Open a pull request + +Push your branch and open a pull request against `main`. Draft pull requests are welcome when you +want early feedback. Complete the repository template with: + +- the linked issue, using `Closes #123` when the PR fully resolves it; +- a concise explanation of what changed and why; +- compatibility or safety impact, including `None` when not applicable; +- the exact commands used to validate the change. + +Keep review follow-ups in the same focused branch and avoid unrelated formatting or refactoring. +Maintainers may ask for smaller scope, additional edge-case tests, or documentation before merge. Please keep changes clear, focused, and well tested. By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). diff --git a/README.md b/README.md index 89a3d97..52aa1ef 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,15 @@ Run without a subcommand to use the interactive menu: creator-toolkit ``` +## Contributing + +Looking for a first contribution? Browse open +[`good first issue`](https://github.com/HoungDev/creator-toolkit-cli/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) +or [`help wanted`](https://github.com/HoungDev/creator-toolkit-cli/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22) +work, comment with your intended approach, and follow the +[contributor guide](https://github.com/HoungDev/creator-toolkit-cli/blob/main/CONTRIBUTING.md). +Focused documentation, testing, bug-fix, and small feature pull requests are welcome. + ## Development ```bash @@ -129,7 +138,7 @@ pytest ``` See [CONTRIBUTING.md](https://github.com/HoungDev/creator-toolkit-cli/blob/main/CONTRIBUTING.md) -for the full contribution workflow. Bug reports and focused pull requests are welcome. +for setup, validation, demo generation, and pull request expectations. Maintainers should follow the [release checklist](https://github.com/HoungDev/creator-toolkit-cli/blob/main/docs/releasing.md)