Mirror of https://github.com/roostorg/osprey
github.com/roostorg/osprey
1# Development Workflow
2
3## Branch Management
4
5- **Branch naming convention**: Use `github_username/description` format (e.g., `caidanw/feature-auth`, `caidanw/fix-database-timeout`)
6- **Base branch**: Always branch from `main`
7- **Create new branch**: `git checkout -b username/feature-name`
8
9## Code Quality Standards
10
11### Automated Checks
12
13Every commit automatically runs:
14
151. **Trailing whitespace removal**
162. **End-of-file fixing**
173. **YAML/JSON/TOML validation**
184. **Ruff linting and formatting**
19
20### Manual Checks
21
22Before pushing, run:
23
24```bash
25# Comprehensive linting check
26uv run ruff check
27
28# Format all code
29uv run ruff format
30
31# Type checking (on specific files/modules)
32uv run mypy osprey_worker/src/osprey_worker/lib
33# Or you can type check every module (this will happen in CI)
34uv run mypy .
35
36# Run all pre-commit hooks
37uv run pre-commit run --all-files
38```
39
40## Commit Standards
41
42Follow [Conventional Commits](https://www.conventionalcommits.org/) format:
43
44```
45feat: add user authentication system
46fix: resolve database connection timeout
47docs: update API documentation
48refactor: simplify rule evaluation logic
49```
50
51**Examples:**
52
53- `feat:` - New features
54- `fix:` - Bug fixes
55- `docs:` - Documentation changes
56- `refactor:` - Code refactoring
57- `test:` - Adding or updating tests
58- `chore:` - Maintenance tasks
59
60## Making Changes
61
621. **Create a new branch:**
63
64 ```bash
65 git checkout -b username/feature-name
66 ```
67
682. **Make your changes**
69
703. **Run quality checks:**
71
72 ```bash
73 uv run ruff check --fix
74 uv run ruff format
75 ```
76
774. **Test your changes** (if tests exist)
78
795. **Commit your changes:**
80
81 ```bash
82 git add .
83 git commit -m "feat: descriptive commit message"
84 ```
85
86 Pre-commit hooks will run automatically and may fix formatting issues.
87
886. **Push your branch:**
89
90 ```bash
91 git push origin username/feature-name
92 ```