iot-dc3/docs/en/development/changelog.md

title

title
Changelog

Changelog

This changelog isn't hand-written. It's generated by make changelog, which reads the git history and groups commits by version following Conventional Commits. This page covers where the list comes from, how to read it, and the rules behind the version numbers and tags, then inlines the full list.

You are here to find what changed in a release or how this list is maintained. To write code, start with the Development Overview & Conventions. For commit conventions, see the Contributing Guide.

Where this list comes from

The platform has no hand-written CHANGELOG. Every change is tracked through normalized commit messages. At release time a script walks the git history, reads the type and scope of each commit, and groups them into the versioned list below. So commit messages are the source data for the changelog — a vague update or fix bug turns into a useless line in the release notes. The commit convention is what makes this document worth reading.

The generator is dc3/bin/changelog.py — plain Python, no third-party deps. The Makefile target make changelog runs it and writes dc3/doc/CHANGE.md, the same file inlined at the bottom of this page.

flowchart LR
  Commits["git commit history<br/>Conventional Commits"] -->|"make changelog"| Gen["dc3/bin/changelog.py<br/>parse type/scope and aggregate by version"]
  Gen -->|"overwrite"| Change["dc3/doc/CHANGE.md<br/>list classified by version"]
  Change -->|"VitePress @include"| Page["the Complete Changelog section on this page"]

The flow runs one way: the commit history is the only source of data, the script's output lands in CHANGE.md, and this page just inlines it for display. Don't hand-edit entries here — the next make changelog overwrites them.

::: code-group

# Run inside the iot-dc3/ directory
make changelog

# FROM/TO accept any git ref (tag, branch, commit); VERSION is written into the group heading
make changelog FROM=dc3.release.20251005.00 TO=HEAD VERSION=2026.5.17

:::

With no arguments, the generator finds the most recent dc3.release.* tag as the start point, uses HEAD as the end point, and reads the version number from dc3.version in pom.xml. It writes the result back to dc3/doc/CHANGE.md, which this page's include directive then inlines.

::: info Commit it separately when you change it The changelog is a generated artifact. When CHANGE.md is regenerated and ready to commit, use docs(release): update generated changelog — the fixed subject the repo reserves for changelog-only changes. The generator recognizes and skips commits with the docs(release): and chore(release): prefixes, so "update changelog" entries don't clutter the changelog itself. :::

How to read it: by version, then by category

The top level of the list is grouped by version, with one ### <version> heading per version. Under that comes a _Generated on <date>._ line marking when the section was built, then a Summary block (commit count, per-category counts, the busiest scopes, and a few Highlights), and finally the commits broken out by category.

Category order inside each version section is fixed, from most to least noteworthy:

Order	Category	Source commit type
1	Breaking Changes	Any type with ! (e.g. feat!:)
2	Security	security
3	Features	feat / feature
4	Bug Fixes	fix
5	Performance	perf
6	Refactoring	refactor
7	Documentation	docs / doc
8	Build	build
9	CI	ci
10	Tests	test / tests
11	Chores	chore / style / revert
12	Other Changes	Commits that don't follow Conventional Commits

::: info Security is also promoted by keyword The table maps type to category. On top of that, the generator promotes any commit to the Security category when the keywords security / vulnerability / cve / auth bypass appear in its type, scope, or summary (case-insensitive) — even if the type isn't security. That keeps security-related changes from getting buried under fix/refactor. :::

Each entry looks like **<scope>**: <summary> (<short-hash>). The scope comes from the (<scope>) in the commit message, and the short hash in parentheses points at the specific commit. To see what changed in the latest version, jump to the first ### section at the top of the list. To compare two versions, the quickest way is to read the commit counts and Highlights in their Summary lines.

::: tip Commit conventions drive output quality The parsing rule is <type>(<scope>): <english imperative summary>. The type has to be one of the agreed set (feat/ fix/perf/refactor/docs/build/ci/test/chore/style/security/revert); otherwise the commit lands in Other Changes without a category. For the full convention, see the Contributing Guide. :::

Version number and tag rules

Version numbers in the list correspond to git tags created by make tag (dc3/bin/tag.sh), in the format dc3.<type>.<YYYYMMDD>.<NN>:

• <type> comes from the current branch. The develop branch produces develop tags; release / main produce release tags. Other branches can't create tags.
• <YYYYMMDD> is the current date.
• <NN> is a zero-padded two-digit sequence number counting how many tags of that type already exist for the day, starting at 00. So the first release tag of a given day is dc3.release.20260622.00, the second is dc3.release.20260622.01 (example values).

# In the iot-dc3/ directory, on the release branch
make tag
# → produces a tag like dc3.release.20260622.00 and pushes it to origin

By default, make changelog scans from the previous dc3.release.* tag up to HEAD. The normal release flow is: run make tag to cut a new tag, then run make changelog to generate the changes for that segment, then commit the updated CHANGE.md.

::: warning The tag is pushed to the remote make tag ends by running git push origin --tags. That's an outbound operation, so confirm you're on the right branch and that the day's sequence number is correct before running it. :::

Complete Changelog

The content below is inlined from dc3/doc/CHANGE.md and refreshed after each make changelog. Don't hand-edit entries here — the next generation overwrites them.

Further reading

• Development Overview & Conventions — the overall map and coding conventions for secondary development
• Contributing Guide — commit message conventions, the commit-msg hook, and the contribution workflow