78 lines
2.4 KiB
Markdown
78 lines
2.4 KiB
Markdown
---
|
|
title: Contributing
|
|
sidebar_position: 4
|
|
---
|
|
|
|
# Contributing
|
|
|
|
## PR Process
|
|
|
|
1. Create a feature branch from `main`.
|
|
2. Make your changes following the code standards below.
|
|
3. Run tests inside the container (see [Testing](testing.md)).
|
|
4. Run `ruff check .` and `mypy app/` to catch lint and type errors.
|
|
5. Open a pull request with a clear title and description.
|
|
|
|
## Commit Conventions
|
|
|
|
This project uses [Conventional Commits](https://www.conventionalcommits.org/) with [python-semantic-release](https://python-semantic-release.readthedocs.io/) for automated versioning.
|
|
|
|
Commit message format:
|
|
|
|
```
|
|
<type>(<scope>): <description>
|
|
|
|
[optional body]
|
|
```
|
|
|
|
Types: `feat`, `fix`, `docs`, `ci`, `refactor`, `test`, `chore`, `perf`.
|
|
|
|
Examples:
|
|
- `feat(scholars): add bulk import from CSV`
|
|
- `fix(ingestion): handle empty citation blocks`
|
|
- `docs: update configuration reference`
|
|
|
|
## Code Standards
|
|
|
|
### Function Length
|
|
|
|
Maximum 50 lines per function. Break complex logic into small, testable, single-responsibility functions.
|
|
|
|
### DRY
|
|
|
|
Abstract repetitive logic immediately. No duplicate boilerplate for database queries, API responses, or error handling.
|
|
|
|
### Negative Space Programming
|
|
|
|
Use explicit assertions and constraints to define invalid states. Fail fast and early. Do not allow silent failures or cascading malformed data, especially in DOM parsing.
|
|
|
|
### Cyclomatic Complexity
|
|
|
|
Flatten logic. Use early returns and guard clauses instead of deep nesting. No magic numbers.
|
|
|
|
### Domain Service Boundaries
|
|
|
|
All business logic resides in `app/services/<domain>/`. Flat files in the `app/services/` root are strictly prohibited. Each domain owns its own application service, types, and helpers.
|
|
|
|
### API Envelope
|
|
|
|
All `/api/v1` responses use the strict envelope format:
|
|
|
|
- Success: `{"data": ..., "meta": {"request_id": "..."}}`
|
|
- Error: `{"error": {"code": "...", "message": "...", "details": ...}, "meta": {"request_id": "..."}}`
|
|
|
|
### Data Isolation
|
|
|
|
- Scholar tracking is user-scoped.
|
|
- Publications are global, deduplicated records.
|
|
- Read/favorite/visibility state lives on scholar-publication link rows.
|
|
|
|
### Scrape Safety
|
|
|
|
Rate limits and cooldowns are immutable constraints. They prevent IP bans and must not be optimized away or set to zero.
|
|
|
|
## UI Standards
|
|
|
|
- Integrate Tailwind with the preset theming system (`frontend/src/theme/presets/`).
|
|
- Every UI element must have a clear purpose.
|
|
- Clarity through both styling and language.
|