forked from Rockachopa/Timmy-time-dashboard
132 lines
3.0 KiB
Markdown
132 lines
3.0 KiB
Markdown
# CONTRIBUTING.md
|
|
|
|
How to contribute to Timmy Time Mission Control.
|
|
|
|
## Philosophy
|
|
|
|
Read SOUL.md first. Timmy is a sovereignty project — every contribution should
|
|
strengthen the user's control over their own AI, never weaken it.
|
|
|
|
Key values:
|
|
- Useful first, philosophical second
|
|
- Honesty over confidence
|
|
- Sovereignty over convenience
|
|
- Lines of code are a liability — delete as much as you create
|
|
|
|
## Getting Started
|
|
|
|
1. Fork the repo
|
|
2. Clone your fork
|
|
3. Set up the dev environment:
|
|
|
|
```bash
|
|
make install # creates .venv + installs deps
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
See INSTALLATION.md for full prerequisites.
|
|
|
|
## Development Workflow
|
|
|
|
### Branch Naming
|
|
|
|
```
|
|
fix/<description> — bug fixes
|
|
feat/<description> — new features
|
|
refactor/<description> — refactors
|
|
docs/<description> — documentation
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
tox -e unit # fast unit tests (~17s)
|
|
tox -e lint # code quality gate
|
|
tox -e format # auto-format code
|
|
tox -e pre-push # full CI mirror before pushing
|
|
```
|
|
|
|
See TESTING.md for the full test matrix.
|
|
|
|
### Code Style
|
|
|
|
- Python 3.11+
|
|
- Formatting: ruff (auto-enforced via tox -e format)
|
|
- No inline CSS in HTML templates
|
|
- Type hints encouraged but not required
|
|
- Docstrings for public functions
|
|
|
|
### Commit Messages
|
|
|
|
Use conventional commits:
|
|
|
|
```
|
|
fix: correct dashboard loading state (#123)
|
|
feat: add crisis detection module (#456)
|
|
refactor: simplify memory store queries (#789)
|
|
docs: update installation guide (#101)
|
|
test: add unit tests for sovereignty module (#102)
|
|
chore: update dependencies
|
|
```
|
|
|
|
Always reference the issue number when applicable.
|
|
|
|
## Pull Request Process
|
|
|
|
1. Create a feature branch from `main`
|
|
2. Make your changes
|
|
3. Run `tox -e pre-push` — must pass before you push
|
|
4. Push your branch and open a PR
|
|
5. PR title: tag with description and issue number
|
|
6. Wait for CI to pass
|
|
7. Squash merge only — no merge commits
|
|
|
|
**Never:**
|
|
- Push directly to main
|
|
- Use `--no-verify` on git commands
|
|
- Merge without CI passing
|
|
- Include credentials or secrets in code
|
|
|
|
## Reporting Bugs
|
|
|
|
1. Check existing issues first
|
|
2. File a new issue with:
|
|
- Clear title
|
|
- Steps to reproduce
|
|
- Expected vs actual behavior
|
|
- Environment info (OS, Python version)
|
|
- Relevant logs or screenshots
|
|
|
|
Label with `[bug]`.
|
|
|
|
## Proposing Features
|
|
|
|
1. Check existing issues and SOUL.md
|
|
2. File an issue with:
|
|
- Problem statement
|
|
- Proposed solution
|
|
- How it aligns with SOUL.md values
|
|
- Acceptance criteria
|
|
|
|
Label with `[feature]` or `[timmy-capability]`.
|
|
|
|
## AI Agent Contributions
|
|
|
|
This repo includes multi-agent development (see AGENTS.md):
|
|
|
|
- Human contributors: follow this guide
|
|
- AI agents (Claude, Kimi, etc.): follow AGENTS.md
|
|
- All code must pass the same test gate regardless of author
|
|
|
|
## Questions?
|
|
|
|
- Read SOUL.md for philosophy
|
|
- Read IMPLEMENTATION.md for architecture
|
|
- Read AGENTS.md for AI agent standards
|
|
- File an issue for anything unclear
|
|
|
|
## License
|
|
|
|
By contributing, you agree your contributions will be licensed under the
|
|
same license as the project (see LICENSE).
|