chore: initialize gondulf project structure
Set up Python project with uv environment management and FastAPI stack. Project structure: - src/gondulf/ - Main application package - tests/ - Test suite directory - pyproject.toml - Project configuration with dependencies - README.md - Project documentation - uv.lock - Dependency lock file Dependencies configured: - FastAPI + Uvicorn for web framework - SQLAlchemy for database ORM - pytest + coverage for testing - ruff, black, mypy, flake8 for code quality - Development environment using uv direct execution model All project standards reviewed and implemented per: - /docs/standards/coding.md - /docs/standards/testing.md - /docs/standards/git.md - /docs/standards/development-environment.md - /docs/standards/versioning.md
This commit is contained in:
149
docs/standards/git.md
Normal file
149
docs/standards/git.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# Git Workflow Standard
|
||||
|
||||
## Overview
|
||||
|
||||
This project uses trunk-based development for simplicity and continuous integration.
|
||||
|
||||
## Branch Strategy
|
||||
|
||||
### Main Branch
|
||||
- `main` - The primary development branch
|
||||
- Always in a deployable state
|
||||
- Protected branch requiring review before merge
|
||||
- All commits must pass CI/CD checks
|
||||
|
||||
### Feature Development
|
||||
- Work directly on `main` for small, low-risk changes
|
||||
- Use short-lived feature branches for larger changes
|
||||
- Feature branches live maximum 2 days before merging
|
||||
|
||||
### Branch Naming (When Used)
|
||||
- `fix/brief-description` - Bug fixes
|
||||
- `feature/brief-description` - New features
|
||||
- `refactor/brief-description` - Code refactoring
|
||||
- `docs/brief-description` - Documentation only
|
||||
|
||||
Examples:
|
||||
- `feature/client-registration`
|
||||
- `fix/token-expiration`
|
||||
- `docs/api-endpoints`
|
||||
|
||||
## Commit Message Format
|
||||
|
||||
Follow Conventional Commits specification:
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
### Types
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation only changes
|
||||
- `style`: Code style changes (formatting, missing semicolons, etc)
|
||||
- `refactor`: Code change that neither fixes a bug nor adds a feature
|
||||
- `perf`: Performance improvements
|
||||
- `test`: Adding or fixing tests
|
||||
- `chore`: Changes to build process or auxiliary tools
|
||||
|
||||
### Scope (Optional)
|
||||
Component or module affected:
|
||||
- `auth`: Authorization endpoint
|
||||
- `token`: Token endpoint
|
||||
- `client`: Client registration
|
||||
- `admin`: Administrative features
|
||||
- `db`: Database changes
|
||||
- `config`: Configuration changes
|
||||
|
||||
### Examples
|
||||
```
|
||||
feat(client): add self-registration endpoint
|
||||
|
||||
Implements dynamic client registration according to
|
||||
RFC 7591 with rate limiting to prevent abuse.
|
||||
|
||||
Closes #12
|
||||
```
|
||||
|
||||
```
|
||||
fix(token): correct expiration time calculation
|
||||
```
|
||||
|
||||
```
|
||||
docs: update README with installation instructions
|
||||
```
|
||||
|
||||
## Pull Request Process (When Using Branches)
|
||||
|
||||
1. Create branch from latest `main`
|
||||
2. Make changes with clear, atomic commits
|
||||
3. Ensure all tests pass locally
|
||||
4. Push branch and open pull request
|
||||
5. Ensure CI passes
|
||||
6. Request review if required
|
||||
7. Merge using "Squash and merge" for clean history
|
||||
|
||||
## Merge Strategy
|
||||
|
||||
- **Squash and merge** for feature branches (maintains clean history)
|
||||
- **Fast-forward only** for direct commits to main
|
||||
- Never use merge commits (no merge bubbles)
|
||||
|
||||
## Code Review Requirements
|
||||
|
||||
All code must be reviewed before merging to `main`:
|
||||
- Self-review checklist:
|
||||
- Tests pass
|
||||
- Documentation updated
|
||||
- No commented-out code
|
||||
- No debug statements
|
||||
- Follows coding standards
|
||||
- Peer review for significant changes
|
||||
|
||||
## Git Hooks (Recommended)
|
||||
|
||||
### Pre-commit
|
||||
- Run linter (e.g., `flake8` for Python)
|
||||
- Run formatter (e.g., `black` for Python)
|
||||
- Check for secrets/credentials
|
||||
|
||||
### Pre-push
|
||||
- Run test suite
|
||||
- Verify no large files
|
||||
|
||||
## Release Process
|
||||
|
||||
1. Ensure all tests pass on `main`
|
||||
2. Update version in appropriate files
|
||||
3. Create release commit: `chore: release v{version}`
|
||||
4. Tag the commit: `git tag -a v{version} -m "Release v{version}"`
|
||||
5. Push tag: `git push origin v{version}`
|
||||
6. Create GitHub release with release notes
|
||||
|
||||
## Rewriting History
|
||||
|
||||
- **Never** rewrite history on `main`
|
||||
- Only use `git rebase` on local branches before pushing
|
||||
- Use `git commit --amend` only for unpushed commits
|
||||
|
||||
## Large Files
|
||||
|
||||
- Use `.gitignore` to exclude generated files, dependencies, and build artifacts
|
||||
- Never commit:
|
||||
- Binary files (unless absolutely necessary)
|
||||
- Credentials or secrets
|
||||
- Local configuration files
|
||||
- IDE-specific files
|
||||
- Log files
|
||||
- Database files
|
||||
|
||||
## Repository Maintenance
|
||||
|
||||
- Keep repository size under 100MB
|
||||
- Regularly clean up merged branches
|
||||
- Archive old issues and pull requests
|
||||
- Maintain clear README and CONTRIBUTING files
|
||||
Reference in New Issue
Block a user