FossilRepo

fossilrepo / CONTRIBUTING.md

Source Rendered

Blame History Raw 139 lines

1	`# Contributing to Fossilrepo`
2
3	`Thanks for your interest in contributing. This document covers how to get set up, our coding standards, and the PR process.`
4
5	`## Development Setup`
6
7	`### Prerequisites`
8
9	`- Python 3.12+`
10	`- Docker and Docker Compose`
11	`- [uv](https://docs.astral.sh/uv/) (Python package manager)`
12	`- [Ruff](https://docs.astral.sh/ruff/) (linter/formatter)`
13
14	`### Running Locally`
15
16	```bash
17	`git clone https://github.com/ConflictHQ/fossilrepo.git`
18	`cd fossilrepo`
19
20	`# Start infrastructure`
21	`docker compose up -d postgres redis mailpit`
22
23	`# Install dependencies`
24	`uv sync --all-extras`
25
26	`# Run migrations and seed data`
27	`DJANGO_DEBUG=true uv run python manage.py migrate`
28	`DJANGO_DEBUG=true uv run python manage.py seed`
29
30	`# Start the dev server`
31	`DJANGO_DEBUG=true POSTGRES_HOST=localhost uv run python manage.py runserver`
32	```
33
34	`Or use Docker for everything:`
35
36	```bash
37	`docker compose up -d --build`
38	`docker compose exec backend python manage.py migrate`
39	`docker compose exec backend python manage.py seed`
40	```
41
42	`### Default Users`
43
44	- `admin` / `admin` — superuser, full access
45	- `viewer` / `viewer` — read-only permissions
46
47	`## Code Style`
48
49	`We use Ruff for linting and formatting. No debates, no custom configs.`
50
51	```bash
52	`# Check`
53	`ruff check .`
54	`ruff format --check .`
55
56	`# Fix`
57	`ruff check --fix .`
58	`ruff format .`
59	```
60
61	`Key conventions:`
62
63	`- Max line length: 140 characters`
64	`- Imports: sorted by Ruff (isort rules)`
65	`- Quote style: double quotes`
66	`- Target: Python 3.12+`
67
68	`## Codebase Conventions`
69
70	Read [`bootstrap.md`](bootstrap.md) before writing code. It covers:
71
72	- Model base classes (`Tracking`, `BaseCoreModel`)
73	- Soft deletes (never call `.delete()`)
74	- Permission system (`P` enum + project-level RBAC)
75	`- View patterns (HTMX partials, auth checks)`
76	`- Template conventions (dark theme, Tailwind classes)`
77
78	`## Testing`
79
80	`Tests run against a real PostgreSQL database. No mocked databases.`
81
82	```bash
83	`# Run all tests`
84	`DJANGO_DEBUG=true uv run pytest`
85
86	`# Run specific test file`
87	`DJANGO_DEBUG=true uv run pytest tests/test_releases.py`
88
89	`# Run with coverage`
90	`DJANGO_DEBUG=true uv run pytest --cov`
91	```
92
93	`Every PR should:`
94
95	`- Include tests for new features (happy path + permission denied cases)`
96	`- Not decrease test coverage`
97	`- Pass all existing tests`
98
99	`## Pull Request Process`
100
101	1. Fork and branch from `main`. Branch naming: `feature/short-description` or `fix/short-description`.
102
103	2. Write code following the conventions in `bootstrap.md`.
104
105	`3. Write tests. Both allowed and denied permission cases. Assert against database state, not just status codes.`
106
107	`4. Lint and test locally. CI will catch it anyway, but save yourself a round trip.`
108
109	`5. Open a PR with a clear description:`
110	`- What changed and why`
111	`- How to test it`
112	`- Link to any related issues`
113
114	`6. Address review feedback in new commits (don't amend/squash during review).`
115
116	`7. Merge when CI is green and review is approved.`
117
118	`## Reporting Issues`
119
120	`Use [GitHub Issues](https://github.com/ConflictHQ/fossilrepo/issues). Include:`
121
122	`- What you expected to happen`
123	`- What actually happened`
124	`- Steps to reproduce`
125	`- Browser/OS/version if relevant`
126
127	`## Architecture Decisions`
128
129	`Fossilrepo has some non-obvious design choices worth understanding:`
130
131	- No Fossil HTTP server. We read `.fossil` files directly via SQLite (`FossilReader`) and use `fossil http` in CGI mode for sync. No persistent Fossil process, stateless containers.
132	`- Django-backed forum posts supplement Fossil's native forum because Fossil forum posts don't sync via clone/pull.`
133	- Encrypted fields use Fernet (AES-128-CBC + HMAC) keyed from `SECRET_KEY` for SSH keys and OAuth tokens at rest.
134	`- Single org model. Multi-org is possible but not implemented — fossilrepo targets self-hosted single-team deployments.`
135
136	`## License`
137
138	`By contributing, you agree that your contributions will be licensed under the MIT License.`
139

FossilRepo

Keyboard Shortcuts