Skip to content

AGENTS.md

Latest commit

 

History

History
77 lines (50 loc) · 7.26 KB

AGENTS.md

File metadata and controls

77 lines (50 loc) · 7.26 KB
Raw

Repository Guidelines

Project Structure & Module Organization

Baserow is a monorepo. Core Django code lives in backend/src, shared backend tests in backend/tests, and the main Nuxt app in web-frontend/ (modules/, server/, test/, stories/). Paid extensions mirror that layout in premium/backend, premium/web-frontend, enterprise/backend, and enterprise/web-frontend. End-to-end coverage lives in e2e-tests/. Product and contributor docs are in docs/, while deployment recipes are under deploy/.

Build, Test, and Development Commands

Use just from the repo root; it wraps the backend and frontend workflows consistently for local and Docker setups.

  • just init installs dependencies and creates .env.local.
  • just dev up starts the local stack; just dc-dev up -d runs the Docker dev environment.
  • just b test -n=auto runs backend pytest suites in parallel.
  • just b test tests/baserow/core/notifications/utils.py to test a specific file.
  • just f test runs frontend Vitest suites.
  • just lint runs both backend and frontend linters; just fix applies auto-fixes.
  • just b run pre-commit run --files $(git diff --name-only HEAD) lints only the files you've touched on your branch (staged + unstaged); use origin/develop...HEAD instead of HEAD to scope to the whole branch. See docs/development/code-quality.md for details.
  • just b migrate runs Django migrations.

For direct package-manager use, backend commands run through uv and frontend commands through yarn.

Coding Style & Naming Conventions

Python targets Python 3.14, uses 4-space indentation, and is formatted and linted with Ruff (just b lint, just b fix) with an 88-character line length. Follow existing Django app/module naming and keep new tests in test_*.py or *_test.py files. Frontend code uses ESLint, Stylelint, and Prettier (just f lint, just f fix); SCSS should follow BEM-style naming already used in web-frontend/modules. Put frontend styles in a dedicated SCSS file and import it through the appropriate SCSS bundle; do not add <style> or <style scoped> blocks to Vue single-file components. Use $palette-* color variables in CSS; $color-* variables are legacy compatibility aliases and should not be used for new styles.

Localization

When adding or changing UI copy, update the English locale files only. Do not add or edit non-English locale files such as fr.json, es.json, or de.json unless explicitly requested; those translations are managed through Weblate.

Technology Stack

Backend code uses Django, Django REST Framework, Celery, PostgreSQL, Redis, and pytest/pytest-django. Python dependencies are managed with uv.

Frontend code uses Vue 3, Nuxt 4, Vuex, Vite, Vitest, Storybook, SCSS, ESLint, Stylelint, Prettier, and yarn. Render functions must use Vue 3 semantics, for example importing h from vue instead of expecting render(h) to receive it. JSX-bearing frontend files must use a .jsx or .tsx extension so Vite can parse them.

Testing Guidelines

Backend tests use pytest with pytest-django; frontend tests use vitest; browser flows live in e2e-tests/. Add unit tests for backend changes and targeted frontend tests for component or store behavior.

Examples: just b test tests/path/, just b test-coverage, just f test -- --coverage, just f yarn test:core path/to/test.

Commit & Pull Request Guidelines

Recent history favors short, imperative subjects, often with Conventional Commit prefixes such as fix:, feat:, and chore(deps):. Branch from develop, keep PRs focused, and link the related issue or discussion. Include a clear summary, note schema or env changes, attach screenshots for UI work, add a changelog entry when required, and make sure the relevant lint and test commands pass before opening the PR.

Project Skills

Reusable skills live in .agents/skills/. Each subdirectory is a self-contained skill with a SKILL.md that describes when and how to apply it. Use these instead of re-deriving the same workflow from scratch.

Skill directory When to use
add-config-env-var Adding a backend or frontend configuration env var and propagating it through settings, Nuxt runtime config, Docker Compose, docs, consumers, and tests as needed
write-frontend-unit-test Writing or fixing frontend unit tests in web-frontend, premium/web-frontend, or enterprise/web-frontend
create-update-service Creating or updating an integration type or service type in contrib/integrations
create-in-app-notification Creating or updating a Baserow in-app notification for an event, including backend and frontend registration, target routing data, and duplicate-prevention behavior
add-update-builder-element-type Adding or updating an Application Builder element type across backend, frontend, migrations, registration, translations, icons, and targeted tests
manage-backend-layers Adding or changing backend model, handler, service, undoable action, and API view layers using the newer automation modules as the preferred pattern
review-pr Reviewing a pull request, branch, or diff against its actual base: functional verification, conventions, security, compatibility, and a severity-ranked report with ready-to-post comments

Security & Configuration Tips

Do not commit secrets or local overrides. Use .env.local for development, keep production settings in the documented deploy configs, and report vulnerabilities privately via the contact path in CONTRIBUTING.md rather than opening a public issue.

Good practices

  • On a specific branch, always merge backend migrations file instead of creating new ones only if it was created on the very same branch.
  • Django migrations must be executed with zero downtime. This means the new database schema must remain compatible with the previous application version during the deployment.
    • Every new field must define a db_default or accept null values if they are created on a previously existing model.
    • Do not remove fields unless you are certain they are no longer used by the previous application version. Instead, keep the field and add a # TODO ZDM: remove this field in the next version comment so it can be safely removed in a subsequent release.
  • CSS classes respect BEM methodology.
  • When working on translations, only update english unless told otherwise. Other languages are handled with Weblate. Don't nest keys too much, just keep one level of nesting.
  • Prefer composition API for new frontend components

Memory

Before starting work, read MEMORY.md file at same level of AGENTS.md file if it exists for historical context and design decisions. Update that memory file to keep track of the decisions.