[ADD] comprehensive README documentation

Document repository purpose, architecture, workflows, and usage: - CI deployment workflow explanation - Linting tools overview - How to modify CI configuration - How to add new Odoo version support - Configuration files explanation - Secrets setup - Version differences (16.0 vs 18.0)
2026-03-07 16:58:29 +01:00
parent 25e9370cc0
commit 3eadd1f0c4
1 changed files with 170 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,172 @@
 # odoo-elabore-ci

+Centralized CI/CD configuration for Elabore's Odoo repositories.
+
+## Purpose
+
+This repository manages linting and CI configuration centrally for all Odoo repositories (`*-addons` and `*-tools`) in the Elabore organization on Gitea.
+
+**Benefits:**
+- Single, consistent configuration across all repos
+- Automatic updates via deployment workflow
+- Multi-version Odoo support (16.0, 18.0, etc.)
+- Based on OCA (Odoo Community Association) standards
+
+## Architecture
+
+```
+odoo-elabore-ci/
+├── .gitea/workflows/
+│   └── deploy-config.yml        # Automatic deployment workflow
+└── config/
+    ├── common/                   # Shared files (all versions)
+    │   ├── .editorconfig
+    │   └── .gitea/workflows/
+    │       └── pre-commit.yml   # CI workflow deployed to each repo
+    ├── 16.0/                     # Odoo 16.0 configuration
+    │   ├── .eslintrc.yml
+    │   ├── .prettierrc.yml
+    │   ├── .pre-commit-config.yaml
+    │   ├── .pylintrc
+    │   ├── .pylintrc-mandatory
+    │   └── .ruff.toml
+    └── 18.0/                     # Odoo 18.0 configuration
+        ├── eslint.config.cjs
+        ├── prettier.config.cjs
+        ├── .pre-commit-config.yaml
+        ├── .pylintrc
+        ├── .pylintrc-mandatory
+        └── .ruff.toml
+```
+
+## How It Works
+
+### Deployment Workflow (`deploy-config.yml`)
+
+When a push is made to the `main` branch of this repository:
+
+1. The workflow automatically detects available versions (folders in `config/` other than `common/`)
+2. For each `*-addons` or `*-tools` repository in the organization:
+   - For each configured Odoo version (16.0, 18.0, etc.):
+     - Attempts to clone the corresponding branch from the target repo
+     - If it exists: copies `config/common/` then `config/{version}/`
+     - Creates a Pull Request if changes are detected
+
+### CI Workflow (`pre-commit.yml`)
+
+Deployed to each target repository, this workflow runs on every Pull Request:
+
+1. Sets up Python 3.11 environment
+2. Installs and runs `pre-commit` with all configured hooks
+3. Verifies no untracked files were generated
+
+## Linting Tools
+
+| Tool | Purpose | Target Files |
+|------|---------|--------------|
+| **Ruff** | Python linter + formatter | `.py` |
+| **Pylint-Odoo** | Odoo-specific rules | `.py`, `__manifest__.py`, XML |
+| **ESLint** | JavaScript linter | `.js` |
+| **Prettier** | Multi-language formatter | JS, CSS, XML, JSON, YAML, MD |
+| **pre-commit-hooks** | Generic checks | Trailing whitespace, merge conflicts, etc. |
+| **OCA hooks** | Odoo community standards | Manifests, README, translations |
+
+## Usage Guide
+
+### Modifying CI Configuration
+
+1. **Edit files in `config/`**:
+   - `config/common/`: changes applied to all versions
+   - `config/{version}/`: version-specific changes
+
+2. **Commit and push to `main`**:
+   ```bash
+   git add .
+   git commit -m "[IMP] description of change"
+   git push origin main
+   ```
+
+3. **The workflow automatically creates PRs** in all affected repos
+
+### Adding a New Odoo Version
+
+1. **Create the configuration directory**:
+   ```bash
+   mkdir config/{new_version}
+   ```
+
+2. **Copy and adapt files** from the closest version or from an OCA repo:
+   ```bash
+   # Example for Odoo 19.0 based on 18.0
+   cp config/18.0/* config/19.0/
+   ```
+
+3. **Adapt the copied files**:
+
+   | File | Required Changes |
+   |------|------------------|
+   | `.pylintrc` | `valid-odoo-versions=19.0` |
+   | `.pylintrc-mandatory` | `valid-odoo-versions=19.0` |
+   | `.ruff.toml` | `target-version` if Python version changes |
+   | `.pre-commit-config.yaml` | Hook versions if needed |
+
+4. **Commit and push**:
+   ```bash
+   git add config/19.0/
+   git commit -m "[ADD] support for Odoo 19.0 configuration"
+   git push origin main
+   ```
+
+The workflow will automatically detect the new folder and deploy the configuration to repos with a `19.0` branch.
+
+## Secrets Configuration
+
+The workflow requires a Gitea token with the following permissions:
+- Read access to all organization repos
+- Write access (to create PRs)
+
+Configure the `ELABORE_BOT_TOKEN` secret in the repository settings.
+
+## Version Differences
+
+### 16.0 vs 18.0
+
+| Aspect | 16.0 | 18.0 |
+|--------|------|------|
+| ESLint config | `.eslintrc.yml` | `eslint.config.cjs` (flat config) |
+| Prettier config | `.prettierrc.yml` | `prettier.config.cjs` |
+| Node.js | 16.17.0 | 22.9.0 |
+| Prettier | 2.7.1 | 3.3.3 |
+| ESLint | 8.x | 9.x |
+| Additional hooks | - | `whool-init`, `oca-gen-external-dependencies` |
+
+## Configuration Files
+
+### `.pylintrc` vs `.pylintrc-mandatory`
+
+- **`.pylintrc`**: All rules (optional + mandatory), non-blocking mode (`--exit-zero`). Useful for IDEs.
+- **`.pylintrc-mandatory`**: Critical rules only, blocking mode. Used by CI.
+
+### Elabore-Specific Rules
+
+Files are customized for Elabore:
+- `manifest-required-authors=Elabore`
+- URLs pointing to `https://git.elabore.coop/elabore/`
+
+## Contributing
+
+1. Test changes locally with `pre-commit run --all-files`
+2. Follow commit conventions (tags `[IMP]`, `[FIX]`, `[ADD]`, etc.)
+3. Auto-generated PRs should be reviewed before merging
+
+## Resources
+
+- [OCA Maintainer Tools](https://github.com/OCA/maintainer-tools)
+- [OCA Pre-commit Hooks](https://github.com/OCA/odoo-pre-commit-hooks)
+- [Pylint-Odoo](https://github.com/OCA/pylint-odoo)
+- [Ruff](https://docs.astral.sh/ruff/)
+- [Pre-commit](https://pre-commit.com/)
+
+## License
+
+AGPL-3.0