Reference documentation for the contributors of the RERO+ projects: how to set up a development environment, how the team works, and the conventions shared by our Invenio applications and libraries.
Most of what follows applies to every RERO+ project. Where a page documents one project only, it says so at the top; where a convention has per-project variations, they are listed side by side.
Each page is meant to be short and current. When a topic is better documented in the code itself — circulation state charts, end-to-end tests — this repository points there rather than duplicating it.
| Repositories | Shape | |
|---|---|---|
| Applications | rero-ils, sonar, rero-mef | Invenio instances: uv, poe bootstrap/setup/server, Docker services |
| Python libraries | rero-invenio-base, rero-invenio-files, rero-invenio-thumbnails, flask-wiki | published on PyPI, no instance to run: uv sync and poe run_tests |
| Angular | ng-core, rero-ils-ui, sonar-ui | published on npm, installed into an instance's static folder |
They share the same tooling (uv, poe, ruff), the same branch model, the same release automation and the same translation loop — so almost everything on this site applies to all of them.
RERO+ also maintains invenio-sip2, which lives under the inveniosoftware-contrib organisation and follows the upstream Invenio conventions rather than ours.
- Set up a development environment
- Coding recommendations — linting, imports, editor settings
- The Invenio modules our applications are built on
- Git workflow and pull requests
- Development environment — install and run an application
- uv and poe — the Python and task tooling used in every project
- Node versions (nvm)
- Integrating the front-end —
ng-coreintorero-ils-ui/sonar-ui, and those into an application
- Git workflow — branches, deployments, contributor flow
- Pull requests and code review — when a human review is needed, and what a reviewer looks at
- Publishing a release — automated with semantic-release, Python and Angular flavours
- Recommendations — ruff, eslint, imports, typing, serialization
- The Invenio stack — which module owns what, and where its documentation is
- Editor configuration — commit message template and Conventional Commits cheatsheet
- JSON schema guidelines — how to write a schema for a RERO+ application
- Checklist for a new field
- Elasticsearch — mappings, indexing, CLI
- Database migrations — Alembic
- Resource relations — what points to what (RERO ILS)
- Circulation — loan and item state charts (RERO ILS)
- Reserving a range of PIDs (RERO ILS)
- Importing a MARCXML record (RERO ILS)
- Layout charter — buttons, links, form design (RERO ILS)
- Per-organisation customization (RERO ILS)
- Permissions policy — identities, needs, policies and generators
- Users, roles and actions
- Access tokens
- Backend tests — pytest and the
poetasks - End-to-end tests — Playwright (RERO ILS)
- Manual QA protocol — user acceptance testing, in French (RERO ILS)
- Test fixture data (RERO ILS)
- How translations work — extraction, the
translationsbranch, Weblate - Translations workflow — day to day, and at release time
- Weblate configuration — component settings, traps and troubleshooting
Add scripts, tools, examples and explanations — but keep them specific to RERO+. Generic documentation about a third-party tool belongs in that tool's own documentation, and goes stale here.
Prefer writing a page that holds for every project, and flag the exceptions, rather than writing it for one project only. If a page really is project-specific, say so in a note under its title.