Skip to content

Commit dc9dd4e

Browse files
Copilotshenxianpengpre-commit-ci[bot]
authored
docs: Add comprehensive GitHub Copilot development instructions (#270)
* Initial plan * Plan creation and initial repository exploration Co-authored-by: shenxianpeng <3353385+shenxianpeng@users.noreply.github.com> * Create comprehensive .github/copilot-instructions.md with validated commands and timing Co-authored-by: shenxianpeng <3353385+shenxianpeng@users.noreply.github.com> * ci: auto fixes from pre-commit.com hooks --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: shenxianpeng <3353385+shenxianpeng@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent bed0271 commit dc9dd4e

File tree

1 file changed

+219
-0
lines changed

1 file changed

+219
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
# Commit Check Development Instructions
2+
3+
Commit Check is a Python CLI tool and pre-commit hook that validates commit messages, branch naming, author information, and more according to Conventional Commits and Conventional Branch conventions.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
## Working Effectively
8+
9+
### Prerequisites and Setup
10+
```bash
11+
# Install Python dependencies (required)
12+
python3 -m pip install --upgrade pip
13+
python3 -m pip install nox
14+
15+
# Install package in development mode with PYTHONPATH (network timeout workaround)
16+
export PYTHONPATH=/home/runner/work/commit-check/commit-check
17+
python3 -m pip install pyyaml # Core dependency
18+
```
19+
20+
### Build and Package
21+
```bash
22+
# Build wheel package -- NETWORK ISSUES: Often fails due to PyPI timeouts in CI environments
23+
# Takes ~10 seconds when working, ~20+ seconds when timing out
24+
nox -s build
25+
26+
# Manual build workaround when nox fails:
27+
python3 -m pip wheel --no-deps -w dist . # NETWORK ISSUES: Also fails due to build dependencies
28+
29+
# Install wheel (depends on build)
30+
nox -s install-wheel # NETWORK ISSUES: Often fails due to PyPI timeouts in CI environments
31+
```
32+
33+
### Testing
34+
```bash
35+
# Run tests directly (fastest, most reliable) -- takes ~1 second. Set timeout to 30+ seconds.
36+
PYTHONPATH=/home/runner/work/commit-check/commit-check python3 -m pytest tests/ -v
37+
38+
# Alternative: Run tests via nox (may timeout due to network)
39+
nox -s coverage # NETWORK ISSUES: Often fails due to PyPI timeouts, takes 5+ minutes when working
40+
```
41+
42+
### Linting and Code Quality
43+
```bash
44+
# NETWORK ISSUES: nox -s lint often fails due to pre-commit installation timeouts
45+
# Manual workaround for linting:
46+
python3 -m pip install pre-commit # May timeout, retry if needed
47+
pre-commit install --hook-type pre-commit
48+
pre-commit run --all-files --show-diff-on-failure # Takes 2-5 minutes for full run
49+
```
50+
51+
### Documentation
52+
```bash
53+
# NETWORK ISSUES: Documentation builds fail due to external dependencies (fonts.google.com)
54+
# Install docs dependencies (may timeout)
55+
python3 -m pip install sphinx-immaterial sphinx-autobuild
56+
57+
# Build docs -- FAILS due to network restrictions in CI environments
58+
PYTHONPATH=/home/runner/work/commit-check/commit-check sphinx-build -E -W -b html docs _build/html
59+
```
60+
61+
## Validation Scenarios
62+
63+
### Manual Testing (Essential after changes)
64+
Always manually validate functionality with these scenarios:
65+
66+
```bash
67+
# Set PYTHONPATH for direct module execution
68+
export PYTHONPATH=/home/runner/work/commit-check/commit-check
69+
70+
# Test 1: Valid conventional commit message
71+
echo "fix: correct issue with validation" > test_commit.txt
72+
python3 -m commit_check.main --message test_commit.txt
73+
# Expected: Exit code 0 (success)
74+
75+
# Test 2: Invalid commit message format
76+
echo "invalid commit message" > test_commit_invalid.txt
77+
python3 -m commit_check.main --message test_commit_invalid.txt
78+
# Expected: Exit code 1, shows ASCII art rejection and error details
79+
80+
# Test 3: Complex conventional commit with scope and body
81+
echo "feat(api): add new user endpoint
82+
83+
This adds support for creating new users via the REST API.
84+
85+
Breaking Change: API version updated to v2" > test_complex_commit.txt
86+
python3 -m commit_check.main --message test_complex_commit.txt
87+
# Expected: Exit code 0 (success)
88+
89+
# Test 4: Branch name validation
90+
python3 -m commit_check.main --branch
91+
# Expected: Depends on current branch name, should show validation result
92+
93+
# Test 5: Help and version
94+
python3 -m commit_check.main --help
95+
python3 -m commit_check.main --version
96+
97+
# Test 6: Configuration validation
98+
python3 -m commit_check.main --config .commit-check.yml --dry-run
99+
100+
# Test 7: Multiple checks at once
101+
python3 -m commit_check.main --message test_commit.txt --branch --dry-run
102+
103+
# Clean up test files
104+
rm -f test_commit.txt test_commit_invalid.txt test_complex_commit.txt
105+
```
106+
107+
### Integration Testing
108+
```bash
109+
# Test as pre-commit hook
110+
pre-commit try-repo . --verbose --hook-stage prepare-commit-msg
111+
112+
# Test wheel installation
113+
python3 -m pip install dist/*.whl # After running nox -s build
114+
commit-check --help # Verify CLI works
115+
cchk --help # Verify alias works
116+
```
117+
118+
## Known Issues and Workarounds
119+
120+
### Network Connectivity
121+
- **Issue**: PyPI timeouts during pip install in CI environments
122+
- **Workaround**: Use `--timeout=10` flag, install dependencies individually, or use PYTHONPATH for development
123+
124+
### Build System
125+
- **Issue**: nox sessions fail due to dependency installation timeouts
126+
- **Workaround**: Run commands directly with PYTHONPATH instead of nox sessions
127+
128+
### Documentation
129+
- **Issue**: Sphinx build fails due to external font loading (fonts.google.com)
130+
- **Status**: Cannot be fixed in restricted CI environments
131+
132+
## Configuration and Important Files
133+
134+
### Repository Structure
135+
```
136+
.
137+
├── commit_check/ # Main Python package
138+
│ ├── __init__.py # Package configuration and defaults
139+
│ ├── main.py # CLI entry point
140+
│ ├── commit.py # Commit message validation
141+
│ ├── branch.py # Branch name validation
142+
│ ├── author.py # Author validation
143+
│ └── util.py # Utility functions
144+
├── tests/ # Test suite (108 tests)
145+
├── docs/ # Sphinx documentation
146+
├── .commit-check.yml # Default configuration
147+
├── pyproject.toml # Package metadata and build config
148+
├── noxfile.py # Build automation
149+
└── .pre-commit-config.yaml # Pre-commit configuration
150+
```
151+
152+
### Key Files
153+
- **pyproject.toml**: Package configuration, dependencies, entry points
154+
- **noxfile.py**: Automated build tasks (lint, test, build, docs)
155+
- **.commit-check.yml**: Default validation rules for the tool itself
156+
- **commit_check/__init__.py**: Default configuration templates and constants
157+
158+
## Common Commands Summary
159+
160+
| Command | Purpose | Timing | Notes |
161+
|---------|---------|---------|-------|
162+
| `nox -s build` | Build wheel | ~10s | Reliable |
163+
| `pytest tests/` | Run tests | ~1s | Fastest, most reliable |
164+
| `nox -s coverage` | Tests + coverage | 5+ min | Often times out |
165+
| `nox -s lint` | Code quality | 2-5 min | Often times out |
166+
| `python3 -m commit_check.main --help` | CLI help | Instant | Always works |
167+
168+
## Tool Behavior and Features
169+
170+
### Commit Message Validation
171+
- **Conventional Commits**: Enforces standard format: `type(scope): description`
172+
- **Supported types**: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test
173+
- **Scope**: Optional, e.g., `feat(api): add endpoint`
174+
- **Breaking changes**: Supports `!` notation: `feat!: breaking change`
175+
- **Merge commits**: Special handling for merge commit messages
176+
177+
### Branch Name Validation
178+
- **Conventional Branches**: Enforces patterns like `feature/`, `bugfix/`, etc.
179+
- **Allowed prefixes**: bugfix/, feature/, release/, hotfix/, task/, chore/
180+
- **Special branches**: master, main, HEAD, PR-* are allowed
181+
182+
### Author Validation
183+
- **Author name**: Checks for valid name format
184+
- **Author email**: Validates email format
185+
- **Commit signoff**: Checks for "Signed-off-by:" trailer
186+
187+
### Exit Codes
188+
- **0**: All checks passed
189+
- **1**: One or more checks failed
190+
- **Error output**: Colorized ASCII art rejection message with specific error details
191+
192+
## When to Use What
193+
194+
### For Quick Development and Testing
195+
- **Use**: Direct Python module execution with PYTHONPATH
196+
- **Commands**: `PYTHONPATH=/home/runner/work/commit-check/commit-check python3 -m commit_check.main`
197+
- **Best for**: Testing changes, debugging, manual validation
198+
199+
### For Production Builds (when network works)
200+
- **Use**: nox sessions for full build pipeline
201+
- **Commands**: `nox -s build`, `nox -s coverage`, `nox -s lint`
202+
- **Best for**: CI/CD, release preparation, comprehensive testing
203+
204+
### For Isolated Testing
205+
- **Use**: Direct pytest execution
206+
- **Commands**: `PYTHONPATH=/home/runner/work/commit-check/commit-check python3 -m pytest tests/`
207+
- **Best for**: Unit testing, TDD, debugging test failures
208+
209+
### For Pre-commit Integration
210+
- **Use**: pre-commit commands
211+
- **Commands**: `pre-commit try-repo .`, `pre-commit run --all-files`
212+
- **Best for**: Validating hook behavior, testing integration
213+
214+
## Development Workflow
215+
1. **Always** set `export PYTHONPATH=/home/runner/work/commit-check/commit-check`
216+
2. **Always** test CLI functionality manually after changes using validation scenarios above
217+
3. **Always** run `pytest tests/` before committing changes
218+
4. **Always** verify build works with `nox -s build`
219+
5. Avoid relying on nox for dependency installation in CI environments

0 commit comments

Comments
 (0)