Skip to content

Commit f4ce25e

Browse files
56kyle56kyle
committed
docs: replace accidentally copied CONTRIBUTING.md in generated project with a custom one
1 parent 410906d commit f4ce25e

File tree

1 file changed

+176
-27
lines changed

1 file changed

+176
-27
lines changed

‎{{cookiecutter.project_name}}/CONTRIBUTING.md‎

Lines changed: 176 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,193 @@
1-
# Contributing to cookiecutter-robust-python
1+
# Contributing to {{ cookiecutter.project_name }}
22

3-
Thank you for considering contributing to the `cookiecutter-robust-python` template! We welcome contributions that help improve the template, keep its tooling current, and enhance its documentation.
3+
Thank you for your interest in contributing to `{{ cookiecutter.package_name }}`! We welcome bug reports, feature requests, and code contributions that help improve this project.
44

5-
By participating in this project, you are expected to uphold our [Code of Conduct].
5+
By participating in this project, you are expected to uphold our [Code of Conduct](CODE_OF_CONDUCT.md).
66

77
## How to Contribute
88

9-
There are several ways to contribute:
9+
### Reporting Bugs
1010

11-
1. **Reporting Bugs:** If you find an issue with the template itself (e.g., it doesn't generate correctly, the generated project's workflow doesn't work on a specific OS, a tool is misconfigured), please open an issue on the [issue tracker](https://github.com/56kyle/cookiecutter-robust-python/issues). Provide clear steps to reproduce the bug.
12-
2. **Suggesting Enhancements:** Have an idea for a new feature, a different tool choice you think is better, or an improvement to the template structure or documentation? Open an issue on the [issue tracker](https://github.com/56kyle/cookiecutter-robust-python/issues) to discuss your suggestion. Clearly articulate the proposed change and the rationale behind it, ideally referencing the template's philosophy and criteria ([Template Philosophy](https://56kyle.github.io/cookiecutter-robust-python/philosophy.html), [Criteria for Tool Selection](https://56kyle.github.io/cookiecutter-robust-python/criteria.html)).
13-
3. **Submitting Code Contributions:** Ready to contribute code (e.g., fix a bug, implement a suggested enhancement, update a tool version)? Please fork the repository and submit a Pull Request.
11+
If you find a bug, please open an issue on our [issue tracker](https://github.com/{{ cookiecutter.github_user | lower | replace(' ', '-') }}/{{ cookiecutter.project_name.replace('_', '-') }}/issues) with:
1412

15-
## Setting Up Your Development Environment
13+
- A clear description of the bug
14+
- Steps to reproduce the issue
15+
- Expected vs. actual behavior
16+
- Your environment details (Python version, OS, etc.)
17+
- Relevant error messages or logs
1618

17-
Refer to the **[Getting Started: Contributing to the Template](https://56kyle.github.io/cookiecutter-robust-python/getting-started-template-contributing.html)** section in the template documentation for instructions on cloning the repository, installing template development dependencies (using uv), setting up the template's pre-commit hooks, and running template checks/tests.
19+
### Suggesting Features
1820

19-
## Contribution Workflow
21+
For feature requests, please open an issue with:
2022

21-
1. **Fork** the repository and **clone** your fork.
22-
2. Create a **new branch** for your contribution based on the main branch. Use a descriptive name (e.g., `fix/ci-workflow-on-windows`, `feat/update-uv-version`).
23-
3. Set up your development environment following the [Getting Started](https://56kyle.github.io/cookiecutter-robust-python/getting-started-template-contributing.html) guide (clone, `uv sync`, `uvx nox -s pre-commit -- install`).
24-
4. Make your **code or documentation changes**.
25-
5. Ensure your changes adhere to the template's **code quality standards** (configured in the template's `.pre-commit-config.yaml`, `.ruff.toml`, etc.). The pre-commit hooks will help with this. Run `uvx nox -s lint`, `uvx nox -s check` in the template repository for more comprehensive checks.
26-
6. Ensure your changes **do not break existing functionality**. Run the template's test suite: `uvx nox -s test`. Ideally, add tests for new functionality or bug fixes.
27-
7. Ensure the **template documentation builds correctly** with your changes: `uvx nox -s docs`.
28-
8. Write clear, concise **commit messages** following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification where possible, especially for significant changes (fixes, features, chore updates, etc.).
29-
9. **Push** your branch to your fork.
30-
10. **Open a Pull Request** from your branch to the main branch of the main template repository. Provide a clear description of your changes. Link to any relevant issues.
23+
- A clear description of the proposed feature
24+
- The problem it would solve or use case it would address
25+
- Any relevant examples or mockups
26+
- Consideration of potential alternatives
3127

32-
## Updating Tool Evaluations
28+
### Contributing Code
3329

34-
If your contribution involves updating a major tool version or suggesting a different tool entirely, you **must** update the relevant sections in the template's documentation (`docs/topics/` files) to reflect the changes in configuration, behavior, or re-justify the choice based on the current state of the tools and criteria. This is crucial for keeping the documentation accurate and useful over time.
30+
We welcome pull requests! For significant changes, it's best to open an issue first to discuss the approach.
3531

36-
## Communication
32+
## Development Setup
3733

38-
For questions or discussion about contributions, open an issue or a discussion on the [GitHub repository](https://github.com/56kyle/cookiecutter-robust-python).
34+
### Prerequisites
3935

40-
---
36+
- Python {{ cookiecutter.min_python_version }}+ (this project supports Python {{ cookiecutter.min_python_version }}-{{ cookiecutter.max_python_version }})
37+
- [uv](https://docs.astral.sh/uv/) for dependency management
38+
- Git for version control
39+
40+
### Setting Up Your Development Environment
41+
42+
1. **Fork and clone the repository:**
43+
```bash
44+
git clone https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_name.replace('_', '-') }}.git
45+
cd {{ cookiecutter.project_name }}
46+
```
47+
48+
2. **Install dependencies:**
49+
```bash
50+
uv sync
51+
```
52+
53+
3. **Set up pre-commit hooks:**
54+
```bash
55+
uvx nox -s pre-commit -- install
56+
```
57+
58+
4. **Verify your setup:**
59+
```bash
60+
uvx nox -l # List available development tasks
61+
```
62+
63+
## Development Workflow
64+
65+
### Making Changes
66+
67+
1. **Create a feature branch:**
68+
```bash
69+
git checkout -b feature/your-feature-name
70+
# or
71+
git checkout -b fix/your-bug-fix
72+
```
73+
74+
2. **Make your changes** following our coding standards (see below)
75+
76+
3. **Test your changes:**
77+
```bash
78+
# Run the full test suite
79+
uvx nox -s tests-python
80+
81+
# Run tests for a specific Python version
82+
uvx nox -s tests-python-{{ cookiecutter.max_python_version.replace('.', '') }}
83+
84+
# Run a specific test file
85+
uvx nox -s tests-python -- tests/unit_tests/test_specific.py
86+
```
87+
88+
4. **Check code quality:**
89+
```bash
90+
# Format code
91+
uvx nox -s format-python
92+
93+
# Lint code
94+
uvx nox -s lint-python
95+
96+
# Type check
97+
uvx nox -s typecheck
98+
99+
# Security checks
100+
uvx nox -s security-python
101+
102+
# Or run all checks at once
103+
uvx nox -t ci
104+
```
105+
106+
5. **Update documentation if needed:**
107+
```bash
108+
# Build docs locally
109+
uvx nox -s build-docs
110+
```
111+
112+
### Coding Standards
113+
114+
This project follows these standards:
41115

42-
<!-- github-only -->
116+
- **Code formatting:** [Ruff](https://docs.astral.sh/ruff/) (automatically applied by pre-commit)
117+
- **Linting:** Ruff with comprehensive rule set
118+
- **Type checking:** [Pyright](https://github.com/microsoft/pyright)
119+
- **Security:** [Bandit](https://bandit.readthedocs.io/) for security linting
120+
- **Commit messages:** [Conventional Commits](https://www.conventionalcommits.org/) format preferred
121+
- **Testing:** [pytest](https://docs.pytest.org/) with good coverage
122+
123+
### Testing Guidelines
124+
125+
- Write tests for new functionality in the appropriate test directory:
126+
- `tests/unit_tests/` - Fast, isolated unit tests
127+
- `tests/integration_tests/` - Tests that involve multiple components
128+
- `tests/acceptance_tests/` - End-to-end behavior tests
129+
- Aim for good test coverage (check with `uvx nox -s coverage`)
130+
- Use descriptive test names and docstrings
131+
- Mock external dependencies appropriately
132+
133+
## Submitting Changes
134+
135+
### Pull Request Process
136+
137+
1. **Push your branch** to your fork
138+
2. **Open a pull request** with:
139+
- Clear title describing the change
140+
- Description explaining what and why
141+
- Link to any relevant issues
142+
- Note any breaking changes
143+
144+
3. **Ensure CI passes** - all automated checks must pass
145+
4. **Respond to review feedback** if requested
146+
5. **Squash commits** if requested before merge
147+
148+
### Pull Request Guidelines
149+
150+
- Keep changes focused and atomic
151+
- Update documentation for user-facing changes
152+
- Add tests for new functionality
153+
- Follow the existing code style
154+
- Ensure all CI checks pass
155+
156+
## Development Tasks Reference
157+
158+
Common Nox sessions for development:
159+
160+
```bash
161+
# Code quality
162+
uvx nox -s format-python # Format with Ruff
163+
uvx nox -s lint-python # Lint with Ruff
164+
uvx nox -s typecheck # Type check with Pyright
165+
uvx nox -s security-python # Security checks
166+
167+
# Testing
168+
uvx nox -s tests-python # Run full test suite
169+
uvx nox -s coverage # Generate coverage report
170+
171+
# Documentation
172+
uvx nox -s build-docs # Build documentation
173+
174+
# Building
175+
uvx nox -s build-python # Build package
176+
177+
# Run everything CI runs
178+
uvx nox -t ci # All CI checks
179+
```
180+
181+
## Getting Help
182+
183+
- Check existing [issues](https://github.com/{{ cookiecutter.github_user | lower | replace(' ', '-') }}/{{ cookiecutter.project_name.replace('_', '-') }}/issues) and [discussions](https://github.com/{{ cookiecutter.github_user | lower | replace(' ', '-') }}/{{ cookiecutter.project_name.replace('_', '-') }}/discussions)
184+
- Open a new issue for bugs or feature requests
185+
- Start a discussion for questions or ideas
186+
187+
## Recognition
188+
189+
Contributors will be recognized in our release notes and documentation. Thank you for helping make this project better!
190+
191+
---
43192

44-
[code of conduct]: CODE_OF_CONDUCT.md
193+
*This project was generated from the [cookiecutter-robust-python](https://github.com/56kyle/cookiecutter-robust-python) template.*

0 commit comments

Comments
 (0)