1ff8c5108f
Replace hardcoded version strings with build-time injection: - Frontend: Vite __APP_VERSION__ from env or package.json - Backend: APP_VERSION env var exposed via /health endpoint - Docker: build arg propagated through both stages - CI: release workflow extracts version from git tag Document branching strategy and release process in CONTRIBUTING.md. Catch up CHANGELOG with v0.2.0 and Unreleased sections. Sync package.json version to 0.3.0.
166 lines
4.2 KiB
Markdown
166 lines
4.2 KiB
Markdown
# Contributing to Docling Studio
|
|
|
|
Thank you for your interest in contributing to Docling Studio! This guide will help you get started.
|
|
|
|
## Getting Started
|
|
|
|
1. **Fork** the repository on GitHub
|
|
2. **Clone** your fork locally:
|
|
```bash
|
|
git clone https://github.com/<your-username>/Docling-Studio.git
|
|
cd Docling-Studio
|
|
```
|
|
3. **Create a branch** for your work:
|
|
```bash
|
|
git checkout -b feature/my-feature
|
|
```
|
|
|
|
## Development Setup
|
|
|
|
### Backend (Python 3.12+)
|
|
|
|
```bash
|
|
cd document-parser
|
|
python -m venv .venv && source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
pip install ruff pytest pytest-asyncio httpx # dev tools
|
|
uvicorn main:app --reload --port 8000
|
|
```
|
|
|
|
### Frontend (Node 20+)
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
## Code Quality
|
|
|
|
### Backend — Ruff
|
|
|
|
We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting Python code.
|
|
|
|
```bash
|
|
cd document-parser
|
|
ruff check . # lint
|
|
ruff check . --fix # lint with auto-fix
|
|
ruff format . # format
|
|
```
|
|
|
|
### Frontend — TypeScript + ESLint + Prettier
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run type-check # type check (vue-tsc)
|
|
npx eslint src/ # lint
|
|
npx prettier --check src/ # check formatting
|
|
npx prettier --write src/ # auto-format
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
# Backend (99 tests)
|
|
cd document-parser
|
|
pytest tests/ -v
|
|
|
|
# Frontend (81 tests)
|
|
cd frontend
|
|
npm run test:run
|
|
```
|
|
|
|
All tests must pass before submitting a PR.
|
|
|
|
## Submitting Changes
|
|
|
|
1. **Commit** with clear, descriptive messages
|
|
2. **Push** your branch to your fork
|
|
3. Open a **Pull Request** against `main`
|
|
4. Describe **what** changed and **why** in the PR description
|
|
5. Ensure CI passes (tests + build)
|
|
|
|
## Branching Strategy
|
|
|
|
We follow a simplified Git Flow:
|
|
|
|
| Branch | Purpose |
|
|
|--------|---------|
|
|
| `main` | Always stable — latest release merged back |
|
|
| `release/X.Y.Z` | Release preparation (freeze, bugfixes, changelog) |
|
|
| `feature/*` | New features — PR to `main` |
|
|
| `fix/*` | Bug fixes — PR to `main` (or `release/*` for pre-release fixes) |
|
|
| `hotfix/X.Y.Z` | Urgent fix on a released version — PR to `main` |
|
|
|
|
Rules:
|
|
- All PRs target `main` (never stack branches on other feature branches)
|
|
- `release/*` branches are created from `main` when preparing a release
|
|
- `hotfix/*` branches are created from the release tag
|
|
|
|
## Versioning
|
|
|
|
We use [Semantic Versioning](https://semver.org/): `MAJOR.MINOR.PATCH`.
|
|
|
|
- **Source of truth**: the git tag (`vX.Y.Z`)
|
|
- `package.json` version should match the current release branch
|
|
- The build injects the version automatically (Vite `__APP_VERSION__` for frontend, `APP_VERSION` env var for backend)
|
|
|
|
## Release Process
|
|
|
|
1. **Create the release branch** from `main`:
|
|
```bash
|
|
git checkout main && git pull
|
|
git checkout -b release/X.Y.Z
|
|
```
|
|
|
|
2. **On the release branch**, only:
|
|
- Bug fixes
|
|
- Move `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD` in `CHANGELOG.md`
|
|
- Update `version` in `frontend/package.json`
|
|
|
|
3. **Merge into `main`** via PR, then **tag on `main`**:
|
|
```bash
|
|
git checkout main && git pull
|
|
git tag vX.Y.Z
|
|
git push origin vX.Y.Z
|
|
```
|
|
|
|
4. The tag triggers the **release workflow** which builds and pushes the Docker image to `ghcr.io`.
|
|
|
|
### Docker Image Tags
|
|
|
|
| Tag | Description |
|
|
|-----|-------------|
|
|
| `X.Y.Z` | Exact version |
|
|
| `X.Y` | Latest patch of this minor |
|
|
| `latest` | Latest stable release |
|
|
|
|
### Hotfix
|
|
|
|
```bash
|
|
git checkout vX.Y.Z # from the release tag
|
|
git checkout -b hotfix/X.Y.Z+1
|
|
# fix, commit, PR to main
|
|
git tag vX.Y.Z+1 # tag on main after merge
|
|
```
|
|
|
|
### Changelog
|
|
|
|
We follow [Keep a Changelog](https://keepachangelog.com/). Every PR should add a line under `[Unreleased]` in `CHANGELOG.md`. The release branch moves `[Unreleased]` to the versioned section.
|
|
|
|
## Pull Request Guidelines
|
|
|
|
- Keep PRs focused — one feature or fix per PR
|
|
- Add tests for new functionality
|
|
- Update documentation if behavior changes
|
|
- Follow existing code style and conventions
|
|
|
|
## Reporting Issues
|
|
|
|
- Use GitHub Issues to report bugs or request features
|
|
- Include steps to reproduce for bugs
|
|
- Mention your OS, Python/Node version, and Docker version if relevant
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
|