Compare commits

...
Author SHA1 Message Date
Kevin B. 28ac4ee290 update CONTRUBUTING.md 2026-11-17 11:57:31 -05:00
Kevin B. cc3eb05fc5 fix glob pattern and exclude generated file 2026-11-17 10:40:50 -05:00
Kevin B. 5b47c3f28f add coderabbit config 2026-11-17 10:32:25 -05:00
2 changed files with 160 additions and 29 deletions

No files matched your search

+64
View File
@@ -0,0 +1,64 @@
# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
language: "en"
early_access: true
reviews:
profile: "chill"
auto_approvals:
enabled: true
high_level_summary: true
poem: false
review_status: true
review_details: false
review_info: true
review_progress: true
related_issues: true
related_prs: true
suggested_labels: false
in_progress_fortune: false
enable_prompt_for_ai_agents: true
path_filters:
- "!backend/swagger/**"
- "!frontend/src/i18n/**/*.json"
- "!frontend/src/i18n/messages.generated.ts"
path_instructions:
- path: "**/*.go"
instructions: |
- Reduce duplication where there is clear duplication found, prefer consolidated functions.
- Prefer standard library and warn about new third-party packages that could be easily implemented with standard library code.
- Make sure all http apis have proper sanitization for path to prevent path traversal vulnerabilities.
- path: "frontend/src/**/*.vue"
instructions: |
- New files should use <script setup lang="ts"> rather than plain <script>.
- Use the typed t() from useI18n, imported from '@/i18n/index.ts', including in templates of <script setup> files.
- Don't flag $t() uses in older/existing <script> files.
auto_review:
enabled: true
drafts: false
auto_incremental_review: true
auto_pause_after_reviewed_commits: 5
base_branches:
- .*
finishing_touches:
unit_tests:
enabled: false
autofix:
enabled: false
fix_ci:
enabled: false
resolve_merge_conflict:
enabled: false
tools:
phpstan:
enabled: false
fbinfer:
enabled: false
presidio:
enabled: false
biome:
enabled: false # coderabbit uses our repo config and they're using old biome versions, which will fail.
knowledge_base:
web_search:
enabled: true
chat:
auto_reply: true
art: false
+96 -29
View File
@@ -4,8 +4,8 @@ Thank you for your interest in contributing to FileBrowser Quantum! This guide w
## Prerequisites
- **Go 1.25+** (see `backend/go.mod`)
- **Node.js 22.0.0+** with npm 9.0.0+ (see `frontend/package.json`)
- **Go 1.27+** (see `backend/go.mod`)
- **Node.js 22.22.2+** (or 24.15.0+, 26+) and **npm 10.9.0+** (see `frontend/package.json`)
- **Docker** (optional, for containerized development)
- **Git** especially important on Windows -- needed for bash support.
@@ -33,7 +33,8 @@ make dev
```
`make setup` installs all dependencies and creates a test configuration file.
`make run` starts the development server. Note: changes require ctrl+c and re-run.
`make dev` runs the development server and Air together, so frontend and backend changes reload automatically.
`make run` builds the frontend and starts the server once. Note: changes require ctrl+c and re-run.
## Project Architecture
@@ -45,35 +46,42 @@ make dev
- **Indexing**: Real-time search in `backend/pkg/indexing/`
- **Previews**: Image/video/document generation in `backend/internal/preview/`
- **Activity**: Query, recording, and export logic in `backend/internal/activity/`
- **Settings**: Configuration handling in `backend/pkg/settings/`
- **API docs**: Swagger docs in `backend/swagger/`, generated by `make generate-docs`
### Frontend (Vue.js + TypeScript)
- **Framework**: Vue 3 + Vite + TypeScript
- **State**: Custom store in `frontend/src/store/`
- **API Client**: Axios-based in `frontend/src/api/`
- **i18n**: 25+ languages with English as main
- **Components**: Feature-based organization
- **Views and components**: `frontend/src/views/` (pages) and `frontend/src/components/` (feature-based), with shared logic in `frontend/src/composables/`
- **i18n**: 25+ languages with English as the source locale, typed with generated types (see [Translations](#translations-i18n)).
## Development Commands
### Essential Commands
```bash
make dev # Start development server with hot-reloading
make test # Run all tests
make lint # Check code quality
make check-all # Lint + tests
make dev # Start development server with hot-reloading
make test # Run all tests
make lint # Check code quality
make check-all # Lint + tests
make build-frontend # Build frontend only
make build-backend # Build backend only
make build # Build Docker image
make build-backend # Build backend only (embeds the frontend build)
make build # Build frontend and backend
make build-docker # Build Docker image
make generate-docs # Regenerate swagger docs
```
### Frontend Development
Note: consider using make commands above instead.
```bash
cd frontend
npm run lint:fix # Auto-fix linting issues
npm run i18n:sync # Sync translations changes
npm run lint # Biome + i18n checks
npm run lint:fix # Auto-fix Biome issues
npm run typecheck # vue-tsc
npm run test # Vitest
npm run i18n:types # Regenerate i18n types
```
## Testing
@@ -86,7 +94,7 @@ make test-frontend # Frontend unit tests
make test-playwright # E2E tests in Docker
```
E2E tests run with three authentication modes: standard auth, no auth, and proxy auth.
E2E tests are split into projects (for example `general`, `settings`, `sharing`, `noauth`, `jwt`, `proxy`, `oidc` and `previews`). `make test-playwright` runs all of them, and `PROJECT=<name>` runs only one.
## Code Standards
@@ -97,10 +105,52 @@ E2E tests run with three authentication modes: standard auth, no auth, and proxy
- **Errors**: Handle all errors explicitly
### Frontend (Vue.js)
- **Linting**: ESLint with Vue 3 + TypeScript rules
- **i18n**: English is master locale, all text must use `$t('key')`
- **Types**: Use TypeScript everywhere
- **Fix**: Run `npm run lint:fix` before committing
- **Linting**: [Biome](https://biomejs.dev/) (`frontend/biome.json`) and `vue-tsc` for type checking. `make lint-frontend` runs both plus the i18n checks.
- **Components**: New components should use `<script setup lang="ts">`. We are currently migrating from the Options API.
- **Types**: Use TypeScript for new code. Existent `.js` files are being migrated too.
- **i18n**: All user-facing text goes through the typed `t()`, see below.
- **Fix**: Run `npm run lint:fix` before committing.
### Translations
This only covers the basics, visit the [documentation page](https://filebrowserquantum.com/en/docs/contributing/translations/translations/) for more details.
`frontend/src/i18n/locales/en.json` is the master language. Types are generated from it into `frontend/src/i18n/messages.generated.ts`, so keys and `{placeholders}` are checked at compile time.
```ts
import { useI18n } from "@/i18n/index.ts";
const { t } = useI18n();
t("general.all");
```
- Import `useI18n` from `@/i18n/index.ts`. In templates of `<script setup>` in vue files, use the same `t`.
- Every key in `en.json` must be used somewhere in `src/`.
- Use Strings literals and avoid using dynamic keys.
When changing a key in `en.json`:
```shell
make generate-translation-types # regenerate messages.generated.ts
make sync-translations # also translates new keys in the other locales (but needs DEEPL_API_KEY)
make check-translations # run the i18n checks
```
#### Contributing new translations
Language files are located at `frontend/src/i18n/locales`. The master language is `en.json` -- all other languages derive from this one.
To add a new language is very simple:
1. Create `frontend/src/i18n/locales/<your-locale>.json`, for example `es.json`. Start from a copy of `en.json`.
2. Register it in `frontend/src/i18n/locales.ts`, in alphabetical order.
```ts
// 'name': What to display in UI
// 'file': The filename without extension
// 'tag': BCP 47 matching navigator.language
es: { name: 'Español', file: 'es', tag: 'es' }
```
## Build & Deployment
@@ -114,7 +164,9 @@ make build-backend # Build Go binary with embedded assets
### Docker
```bash
make build # Full image with ffmpeg and muPDF
make build-docker # Image with ffmpeg
make build-docker-slim # Slim image
make build-docker-media # Media image
```
### Configuration
@@ -122,21 +174,36 @@ make build # Full image with ffmpeg and muPDF
## Contributing
All changes go into `dev/vX.X.X` branches, so PRs must target one of them. For how `dev` branches are promoted to `beta` and `stable` releases, see the [Release Strategy](https://filebrowserquantum.com/en/docs/contributing/features/feature-development/#release-strategy).
The version in the name decides what the branch is for:
- Higher version (e.g. `dev/v2.2.0`): new features and big changes.
- Lower version (e.g. `dev/v2.1.6`): bug fixes only.
Older `dev` branches may still exist but are no longer in use. Make sure you target the right one: the highest version for features, the newest lower version for bug fixes. Check the releases page to see the current `beta` version.
Always verify if the change you're about to submit exists already in one of the `dev/vX.X.X` branches to avoid duplicates.
### Pull Request Process
1. Fork and create a feature branch
2. Make your changes following the code standards
3. Run `make dev` to build and run with your changes. Supports hot-reloading frontend and backend changes.
4. When ready, run `make check-all` to verify tests and linting
5. Submit PR with a clear description
1. Fork and create a feature branch from the matching `dev/vX.X.X` branch.
2. Make your changes following the code standards.
3. Run `make setup` and `make dev` to build and run with your changes. Supports hot-reloading frontend and backend changes.
4. When ready, run `make check-all` to verify linting, tests, translations and icons. You can also run the Playwright tests locally with `make test-playwright`.
5. Submit PR against the matching `dev/vX.X.X` branch with a clear description.
### PR Requirements
- Clear description of changes
- All tests must pass
- Follow existing code patterns
- Update documentation if needed
- Clear description of changes.
- All tests must pass.
- Follow existing code patterns.
- Update documentation if needed (see our [documentation](https://filebrowserquantum.com) and it's [repository](https://github.com/gtsteffaniak/filebrowserDocs)).
- Regenerate generated files you affect (swagger docs, translation types, icons).
PRs are also reviewed automatically by CodeRabbit.
### Commit Format
```
type(scope): description