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:
2025-11-20 10:42:10 -07:00
commit 6d21442705
17 changed files with 4301 additions and 0 deletions

149
docs/standards/git.md Normal file
View 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