# IoT DC3 Contributor Guide Thank you for contributing to IoT DC3. This guide keeps contributions predictable for maintainers and safe for users. ## Ways to Contribute - Report reproducible bugs with logs, versions, configuration, and steps to reproduce. - Propose features with the target scenario, expected behavior, and compatibility impact. - Improve documentation, examples, translations, and troubleshooting notes. - Submit code changes with focused commits and tests or verification notes. ## Development Environment Use the supported toolchain: - JDK 21 - Maven 3.9+ - Podman or Docker - Make, optional but recommended Start the local dependency stack from the repository root: ```bash make up-db make up-optional ``` For source-run Java processes, load runtime variables from: ```bash source dc3/env/dev.env.sh ``` The root Makefile is the project-level command entry point. The Web application and TypeScript CLI retain independent pnpm packages and lockfiles. See [`docs/development.md`](docs/development.md) for the full command table: ```bash make install-node # install dc3-web and dc3-cli dependencies make dev-auth # one backend service make dev # auth, gateway, data, manager, agentic make check # Java, Web, CLI, and Python quality gates ``` For Compose interpolation, copy the root template first: ```bash cp .env.example .env ``` See the [environment guide](https://docs.dc3.site/en/quickstart/environment) for the difference between `.env.example`, `.env`, `dc3/env/dev.env`, and `dc3/env/dev.env.sh`, including JetBrains IDEA usage. ## Branches and Pull Requests IoT DC3 follows a simplified Git Flow: - `develop` — integration branch. Cut `feature/` branches from `develop` and open pull requests back against `develop`. Full CI (lint / test / build / e2e) runs here. - `main` — production trunk. Verified work is promoted from `develop` to `main` via pull request. A release is published only after the version and generated changelog are committed and the matching `v` tag is explicitly created. - `hotfix/` — cut from `main` for production fixes; open the PR back against `main` (then tag), and back-merge to `develop`. - `release` — archived (read-only). It is kept for history only; do not open pull requests against it. Use descriptive branch names such as `feature//` or `fix//`. Keep pull requests focused — avoid mixing refactors, formatting churn, and behavior changes unless they are necessary for the same fix. Reference related issues in the pull request description. ## Commit Messages Use concise Conventional Commit-style subjects: ```text fix(manager): validate tenant scope for device queries docs(env): explain JetBrains IDEA environment variables refactor(container): deduplicate compose registry overrides ``` Allowed types are `feat`, `fix`, `perf`, `refactor`, `docs`, `build`, `ci`, `test`, `chore`, `style`, `security`, and `revert`. Use English, keep the subject specific, and avoid vague descriptions such as `update`, `fix`, `misc`, `wip`, or `.` because release notes are generated from commit history. A commit that only updates the generated changelog must use exactly `docs(release): update generated changelog`, and it must be kept separate from behaviour, configuration, or tooling changes so the generator can skip it. The repository provides a Husky `pre-commit` hook under `.husky/`. After frontend dependencies are installed, it runs lint-staged and applies ESLint to staged JavaScript, TypeScript, and Vue files. ## Build and Verification Before opening a pull request, run the checks that match the touched area: ```bash mvn -s .mvn/settings.xml clean package podman compose -f dc3/docker-compose-db.yml config ``` For documentation-only changes, at least check links, commands, and formatting manually. For container changes, run `make config STACK=` or `podman compose config` for every touched compose file. ## Release Notes Before tagging a release, generate the categorized changelog from git: ```bash make changelog ``` `dc3/doc/CHANGE.md` is generated from Git history: do not hand-edit the current release block unless fixing generator output. By default the command reads the current version from `pom.xml`, compares `HEAD` with the latest reachable `v*` (semver) tag, and updates `dc3/doc/CHANGE.md`. You can override the range or version when needed: ```bash make changelog FROM= TO=HEAD VERSION= ``` The root `pom.xml` version is the release identity. Update and commit that version and the generated changelog first, then switch to a clean, up-to-date `main` and create the matching tag: ```bash make tag # pom.xml -> annotated tag v ``` `bash dc3/bin/tag.sh --dry-run` previews the exact tag without pushing. The script refuses dirty, non-`main`, out-of-date, duplicate, or malformed-version releases. It only pushes the annotated tag; the `Docker Images` workflow then reruns backend and web verification, checks that the tag matches `pom.xml`, publishes images, and creates the GitHub Release. Configure the `release` environment with required reviewers, protected `v*` tags, and the registry credentials. A manual workflow run performs a non-publishing build unless it targets an existing matching `v*` tag. Generated changelog-only release commits are skipped by default so rerunning the command after committing `CHANGE.md` remains stable. Set `INCLUDE_CHANGELOG_COMMITS=true` only when those commits should appear in release notes. ### Backfilling Missing Releases Every version recorded in `CHANGE.md` should end up with a GitHub Release. When a release window is skipped (a version is committed to `CHANGE.md` but never tagged), close the gap without re-tagging history: ```bash make release-backfill # dry-run: list CHANGE.md versions that have no release make release-backfill-apply # create them (gh CLI, authenticated) ``` The tool maps each date-formatted version to the last commit dated on or before that version day, assembles the release body from `TITLE.md` + the version's changelog block + the `RELEASE-FOOTER.md` quick start (deep usage and deployment content lives on docs.dc3.site), and creates the tag through the GitHub API — which does **not** trigger the `Docker Images` workflow and never moves the `latest` pointer. When `TITLE.md` or `RELEASE-FOOTER.md` evolves, `make release-backfill-refresh` re-renders the bodies of already-backfilled releases. Run the dry-run periodically to catch drift between `CHANGE.md` and the release list. ## Coding Guidelines - Follow the existing package structure, naming, validation, exception, logging, and facade patterns. - Keep tenant-aware behavior explicit. New queries, gRPC calls, cache keys, and data mutations must preserve tenant scope. - Prefer typed configuration properties with validation over scattered `@Value` usage for grouped settings. - Add tests or focused verification for behavior changes, especially shared common modules and cross-service contracts. - Do not commit secrets, generated local files, IDE metadata, or machine-specific configuration. ## Documentation and Translation When changing root README content, keep `README.md`, `README.zh.md`, `README.es.md`, `README.ja.md`, `README.ko.md`, `README.ru.md`, and `README.vi.md` structurally aligned. If a translated update is not possible in the same pull request, call it out clearly in the pull request description. ## License IoT DC3 Community Edition is licensed under the GNU Affero General Public License v3.0 or later. See `LICENSE-AGPL.txt` and `LICENSE.txt` for the project license notice.