Skip to content

Commit e99c66c

Browse files
committed
Enhance contributing.md with development workflow
Added comprehensive sections: - Development Setup: Prerequisites, quick start, running tests - Code Quality: Commands for check, typecheck, format - Building Documentation: Commands for docs and link checking - Pull Request Guidelines: Before submitting checklist, commit message standards (no AI mentions), submission workflow Expanded from 17 to 103 lines with actionable guidance.
1 parent aca0644 commit e99c66c

File tree

1 file changed

+87
-1
lines changed

1 file changed

+87
-1
lines changed

docs/source/contributing.md

Lines changed: 87 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,95 @@
44

55
The sources are in a GIT DVCS with its main branches at [Github](https://github.com/mxstack/mxmake).
66

7+
## Development Setup
8+
9+
### Prerequisites
10+
11+
- Python 3.9 or later
12+
- Git
13+
- make
14+
15+
### Quick Start
16+
17+
Clone the repository and set up the development environment:
18+
19+
```bash
20+
git checkout https://github.com/mxstack/mxmake.git
21+
cd mxmake
22+
make install
23+
```
24+
25+
This will:
26+
- Create a virtual environment (`.venv`)
27+
- Install mxmake in development mode
28+
- Install all development dependencies
29+
30+
### Running Tests
31+
32+
```bash
33+
make test # Run all tests
34+
make coverage # Run tests with coverage report
35+
```
36+
37+
### Code Quality
38+
39+
```bash
40+
make check # Run all QA checks (ruff, isort)
41+
make typecheck # Run type checking (mypy)
42+
make format # Auto-format code
43+
```
44+
45+
### Building Documentation
46+
47+
```bash
48+
make docs # Build Sphinx documentation
49+
make docs-linkcheck # Check for broken links in docs
50+
```
51+
52+
Documentation will be built in `docs/build/html/`.
53+
54+
## Pull Request Guidelines
55+
56+
### Before Submitting
57+
58+
1. **Run tests**: Ensure all tests pass with `make test`
59+
2. **Check code quality**: Run `make check` and `make typecheck`
60+
3. **Update tests**: Add tests for new features or bug fixes
61+
4. **Update documentation**: Document new features in `docs/source/`
62+
63+
### Commit Messages
64+
65+
- Keep commits concise (max 3 lines preferred)
66+
- Focus on what changed and why
67+
- Write as if a human developer wrote them
68+
- **Never mention AI assistance or Claude in commits**
69+
- Use standard git conventions
70+
71+
**Good examples**:
72+
```
73+
Fix UV_PYTHON default value to prevent empty parameter error
74+
75+
Add migration guide documenting breaking changes
76+
```
77+
78+
**Bad examples**:
79+
```
80+
Fixed stuff with Claude's help
81+
82+
Updated code (generated with AI)
83+
```
84+
85+
### Submitting
86+
87+
1. Create a feature branch: `git checkout -b feature/my-feature`
88+
2. Make your changes and commit
89+
3. Push to GitHub: `git push origin feature/my-feature`
90+
4. Open a Pull Request on GitHub
91+
5. Wait for CI to pass and address review feedback
92+
793
## Copyright & Licence
894

9-
- Copyright (c) 2022-2024 MXStack Contributors
95+
- Copyright (c) 2022-2025 MXStack Contributors
1096
- under 2-Clause BSD License (aka Simplified BSD License)
1197
- see LICENSE.md
1298

0 commit comments

Comments
 (0)