182 lines
5.3 KiB
Markdown
182 lines
5.3 KiB
Markdown
# Contributing Guide
|
|
|
|
## Purpose
|
|
This repository is the standalone productized Workdock platform.
|
|
|
|
Use this file as the quick-start guide for future coders. It complements:
|
|
- `DEPLOYMENT.md`
|
|
- `TUBCO_SETUP.md`
|
|
- `backend/workflows/templates/workflows/project_wiki.html`
|
|
- `backend/workflows/templates/workflows/developer_handbook.html`
|
|
|
|
If you change architecture, deployment flow, or operational behavior, update the relevant documentation in the same branch.
|
|
|
|
## Branch Policy
|
|
- `develop`: active integration branch
|
|
- `main`: stable branch for production promotion
|
|
- short-lived feature branches: branch from `develop`, merge back into `develop`
|
|
- customer release branches: branch from `main` for a frozen customer line when a customer must not receive future feature work automatically
|
|
|
|
Do not use `main` as the default development branch.
|
|
|
|
### Customer release policy
|
|
For customer-specific deliveries such as TUBCO, use a dedicated release branch from the current stable line.
|
|
|
|
Recommended pattern:
|
|
- `release/tubco-v1`: customer maintenance branch
|
|
- `tubco-baseline-2026-03`: baseline tag taken from the same stable point
|
|
|
|
Rule:
|
|
- new product features continue on `develop`
|
|
- customer release branches only receive approved:
|
|
- bug fixes
|
|
- security updates
|
|
- UI improvements
|
|
|
|
Do not let a customer deployment track `develop` directly.
|
|
|
|
Use `TUBCO_SETUP.md` for the customer-specific bootstrap, reset, config-sync, and deploy sequence.
|
|
|
|
## Dual Remote Workflow
|
|
This repository now has two different Git remotes with different purposes:
|
|
- `origin`: the normal GitHub product remote
|
|
- `tubco`: the TUBCO customer remote
|
|
|
|
Use the helper command to avoid mixing them up:
|
|
|
|
```bash
|
|
./scripts/git_remote_target.sh status
|
|
```
|
|
|
|
Common commands:
|
|
|
|
```bash
|
|
./scripts/git_remote_target.sh push-origin
|
|
./scripts/git_remote_target.sh push-tubco release/tubco-v1
|
|
./scripts/git_remote_target.sh set-own-identity
|
|
./scripts/git_remote_target.sh set-tubco-identity
|
|
```
|
|
|
|
Default rule:
|
|
- normal product work goes to `origin`
|
|
- TUBCO pushes happen only when explicitly requested
|
|
|
|
Safety rules in this repo:
|
|
- plain `git push` should default to `origin`
|
|
- pushes to `tubco` are guarded by a repo-local `pre-push` hook
|
|
- only these refs should go to `tubco`:
|
|
- `release/tubco-*`
|
|
- `tubco-baseline-*`
|
|
|
|
Authentication rule:
|
|
- prefer a personal access token for the `tubco` HTTPS remote
|
|
- do not rely on a reusable account password long term
|
|
- store the PAT through macOS keychain using the repo-local `credential.helper=osxkeychain` setting
|
|
|
|
## Current Delivery Model
|
|
- GitHub Actions is used for CI
|
|
- the current test server is local/LAN-only
|
|
- deployment to the test server is manual from a LAN-connected machine
|
|
|
|
Standard test deployment command:
|
|
|
|
```bash
|
|
./scripts/deploy_test_from_mac.sh
|
|
```
|
|
|
|
Destructive fresh reset command:
|
|
|
|
```bash
|
|
RESET_CONFIRM=RESET EXPECTED_BRANCH=develop ./scripts/reset_stack_from_mac.sh
|
|
```
|
|
|
|
Why:
|
|
- GitHub-hosted runners cannot reliably reach the private LAN target at `192.168.2.55`
|
|
|
|
## Architecture Summary
|
|
Main stack:
|
|
- Django
|
|
- Celery
|
|
- PostgreSQL
|
|
- Redis
|
|
- Caddy
|
|
|
|
Important repository areas:
|
|
- `backend/config/`: Django configuration
|
|
- `backend/workflows/`: application code
|
|
- `backend/workflows/templates/workflows/`: templates and in-app documentation
|
|
- `backend/workflows/static/workflows/`: CSS and JS
|
|
- `backend/workflows/pdf_assets/`: default PDF HTML templates and default letterhead
|
|
|
|
Current backend modularization:
|
|
- `views.py`: thin route wrapper layer
|
|
- split view modules:
|
|
- `request_views.py`
|
|
- `account_views.py`
|
|
- `admin_config_views.py`
|
|
- `form_builder_views.py`
|
|
- `observability_views.py`
|
|
- `integration_admin_views.py`
|
|
- `welcome_email_views.py`
|
|
- `intro_builder_views.py`
|
|
- `tasks.py`: async task entrypoints/orchestration
|
|
- `pdf_rendering.py` and `pdf_sections.py`: PDF rendering
|
|
- `email_workflows.py` and `notification_dispatch.py`: mail/notification orchestration
|
|
- `models.py`: stable import facade over split model modules
|
|
|
|
## Engineering Rules
|
|
1. Preserve runtime behavior while refactoring.
|
|
2. Prefer shared UI/system primitives over page-local one-off patterns.
|
|
3. Do not silently overwrite environment-specific configuration data.
|
|
4. Treat database-backed admin configuration as runtime state, not seed data.
|
|
5. Update docs when workflow or architecture changes.
|
|
|
|
## Code vs Data
|
|
Not all visible behavior comes from code.
|
|
|
|
Code-driven:
|
|
- page layout
|
|
- permissions
|
|
- routing
|
|
- task behavior
|
|
- deploy scripts
|
|
|
|
Database-driven:
|
|
- app registry order and visibility
|
|
- branding and company config
|
|
- builder settings
|
|
- intro checklist items
|
|
- notification templates and rules
|
|
|
|
If local UI and server UI differ, check the database-backed config before assuming a code drift.
|
|
|
|
## Testing Rules
|
|
Minimum validation after non-trivial changes:
|
|
|
|
```bash
|
|
docker compose exec -T web python manage.py check
|
|
docker compose exec -T web python manage.py test
|
|
```
|
|
|
|
Also verify specifically when changing:
|
|
- PDFs
|
|
- deployment/config
|
|
- templates/UI
|
|
|
|
## Documentation Rules
|
|
Keep these current:
|
|
- `DEPLOYMENT.md`
|
|
- `PRODUCTIZATION_ROADMAP.md`
|
|
- `backend/workflows/templates/workflows/project_wiki.html`
|
|
- `backend/workflows/templates/workflows/developer_handbook.html`
|
|
|
|
## Recommended Change Flow
|
|
1. Start from `develop`
|
|
2. Implement the change
|
|
3. Validate locally
|
|
4. Update docs if needed
|
|
5. Push to GitHub
|
|
6. Let CI run
|
|
7. Deploy from the Mac if runtime verification is needed
|
|
8. Promote `develop` to `main` when stable
|