Skip to the content.

Preparing a New Release

Update the new version number

VERSION in rules/common.mk is the single version source: the build passes it to every object (-DVERSION) and names the libraries after it (sdk/lib/libmmt_core.so.<VERSION>). bash scripts/validate-release-prep.sh compares every site below with it and fails on any disagreement; it runs on every pull request (the version-agreement job in .github/workflows/c-cpp.yml) and again in the release workflow’s verify-tag job, which also requires the pushed tag to equal v<VERSION> and its commit to be on main — an ancestor of origin/main (tools/ci/check-release-tag.sh).

The release workflow is the only publisher. Never create a GitHub Release by hand (gh release create, the web UI’s Draft a new release, an upload of assets): pushing the tag is the whole publication step. Once every gate passes, the release job of .github/workflows/release-packages.yml creates the Release with tools/ci/publish-release.sh — as a draft carrying every package, SBOM and SHA256SUMS (each covered by the build-provenance attestation), then published — and it refuses to run when a Release a person made for the tag already exists, deleting nothing. Re-running a tag run after the workflow published exits 0 (“already published”) when the Release holds every asset, so it raises no alert (issue #595). When any job of a tag run fails, the release-alert job opens (or comments on) an issue titled Release workflow failed for vx.y.z; nothing is published, so fix the cause and re-run the workflow, or delete the tag and push it again. Do not publish around a failed run.

Declared version — bump these together, at the start of the release cycle, to the version being prepared; each must equal VERSION exactly:

Site What the check reads
rules/common.mk VERSION := x.y.z (the source)
src/mmt_core/public_include/mmt_core.h #define VERSION "x.y.z" (fallback for consumers that do not pass -DVERSION)
mmt-dpi.spec Version: x.y.z (with a matching top %changelog entry - x.y.z-1)
CHANGELOG.md the topmost Version x.y.z (...) heading — (unreleased) until the tag, then the release date
debian/changelog the first entry’s upstream version — checked only when the file exists

Published release — the one-command installer pins the latest published tag, so these lag VERSION between the bump and the tag (a tagged commit cannot pin its own commit SHA). They must all name the same tag as install.sh, and that tag must be at or below v<VERSION> and have a dated CHANGELOG.md entry:

Site What the check reads
install.sh RELEASE_TAG="vx.y.z" (with RELEASE_TAG_SHA, the peeled commit the tag resolves to — tools/ci/check-release-tag.sh fails when it is not)
README.md Current release: [vx.y.z] and pinned release tag (`vx.y.z`)
docs/_includes/quick-start.md pinned release tag (`vx.y.z`)
docs/index.html the hero eyebrow vx.y.z · Apache-2.0 · …
.github/workflows/c-cpp.yml ABI_BASELINE: vx.y.z of the abi-diff job (issue #536)
tools/ci/abi-diff.sh baseline_ref=vx.y.z, the script’s default baseline

ABI and SOVERSION (issue #536) — every shared library carries the SONAME lib<name>.so.<SOVERSION> (SOVERSION at the end of rules/common.mk), independent of VERSION. Bump SOVERSION in the pull request that makes an incompatible change to an installed library (a public struct layout, a removed or re-typed export), and record the break in the CHANGELOG.md section of the next version: the required abi-diff job compares the libraries with the ABI_BASELINE tag and fails on an incompatible change whose SONAME did not move. A compatible change (an added export) keeps SOVERSION.

Release order:

  1. Bump the declared-version sites and open the new Version x.y.z (unreleased) section in CHANGELOG.md.
  2. When cutting the release, replace (unreleased) with the release date in a pull request, merge it, then tag that merged commit on main vx.y.z (never a release branch: a tag that is not an ancestor of origin/main fails verify-tag) and push the tag. The workflow publishes the Release. Tag the merged commit by its SHA (sha=$(gh pr view <N> --json mergeCommit --jq .mergeCommit.oid), then git tag -a vx.y.z -m "MMT-DPI x.y.z" "$sha"), not the main tip, which may have moved since. Then check that the Release holds exactly the expected assets: for each package in its manifest.json, the alias (file), the package (source) and its .sbom.json; plus install.sh, manifest.json, SHA256SUMS, mmt-dpi.intoto.jsonl and the source tarball and its .asc signature. There are two packages (mmt-dpi, mmt-dpi-security) per leg of the package matrix of release-packages.yml. v1.10.0 had 18 legs, 36 packages and 113 assets, so a count floor would pass a Release missing most of its SBOMs:

    t=vx.y.z; d=$(mktemp -d)
    gh release download "$t" --repo Montimage/mmt-dpi -p manifest.json -D "$d"
    diff <(gh release view "$t" --repo Montimage/mmt-dpi --json assets --jq '.assets[].name' | LC_ALL=C sort) \
         <({ jq -r '.packages[] | .file, .source, .source + ".sbom.json"' "$d/manifest.json"
             printf '%s\n' install.sh manifest.json SHA256SUMS mmt-dpi.intoto.jsonl "mmt-dpi-${t#v}.tar.gz" "mmt-dpi-${t#v}.tar.gz.asc"; } | LC_ALL=C sort) \
      && echo "asset set complete: $(jq '.packages | length' "$d/manifest.json") packages"
    
  3. After the tag is published, update the published-release sites in one follow-up PR: run bash tools/ci/check-release-tag.sh --write-pin vx.y.z, which writes RELEASE_TAG and RELEASE_TAG_SHA from the peeled tag (git rev-parse vx.y.z^{commit}, never the annotated tag object), then update the README/site mentions and the ABI baseline (ABI_BASELINE of the abi-diff job and tools/ci/abi-diff.sh’s baseline_ref; the job downloads that tag’s ubuntu-24.04 .deb) — version-agreement fails until all of them name the same tag.
  4. Once that follow-up PR is merged, the published one-liner installs the new tag: run the Install smoke workflow (.github/workflows/install-smoke.yml, Run workflow, source: published) and check that every supported leg passed. The workflow also runs by itself after the tag run and weekly, but the run after the tag still exercises the previous pin until step 3 lands. A failing supported leg on a scheduled or post-release run opens (or comments on) an issue titled Install smoke matrix failing.

Cutting v1.9.1 (issue #493)

VERSION is already 1.9.1 and CHANGELOG.md opens with Version 1.9.1 (unreleased) (#483, #592), while install.sh still pins v1.9.0. Neither the date nor the repin can land before the tag exists: --write-pin needs the tag’s peeled commit. In order:

  1. Date the changelog. A PR replacing (unreleased) with the release date in CHANGELOG.md; merge it once version-agreement is green.
  2. Tag that merged commit on main by its SHA, not the main tip: sha=$(gh pr view <N> --json mergeCommit --jq .mergeCommit.oid) for the step-1 PR, git fetch origin main && git tag -a v1.9.1 -m "MMT-DPI 1.9.1" "$sha", then git merge-base --is-ancestor v1.9.1 origin/main && echo "on main".
  3. Push the tag: git push origin v1.9.1. This starts release-packages.yml; do not create the Release by hand.
  4. Check the tag run: verify-tag, release-gates and Publish GitHub Release all succeeded (none skipped); the Release holds exactly the expected assets (the check in step 2 of Release order above, with t=v1.9.1); and gh attestation verify mmt-dpi_*_ubuntu-24.04_x86_64.deb --repo Montimage/mmt-dpi passes on a downloaded .deb. The verified bootstrap set (issue #498) is there too: install.sh, manifest.json, mmt-dpi.intoto.jsonl and one mmt-dpi[-security]_<distro>_<amd64|arm64>.<deb|rpm> alias per package, and the Bootstrap smoke workflow run that follows the tag run is green.
  5. Repin the installer in a follow-up PR: bash tools/ci/check-release-tag.sh --write-pin v1.9.1, then update Current release: [v1.9.1] and pinned release tag (`v1.9.1`) in README.md / docs/_includes/quick-start.md (then bash tools/ci/check-doc-includes.sh --write) and the hero eyebrow in docs/index.html; bash scripts/validate-release-prep.sh must pass.
  6. Run the smoke matrix against the published one-liner once that PR is merged (step 4 of Release order above).

Landing 1.10.0 in Montimage/mmt-dpi (issue #751)

The 1.10.0 cycle moves the montimage-projects/mmt-dpi tree into the public Montimage/mmt-dpi through the draft PR Montimage/mmt-dpi#41 (release/v1.10.0 → main, a fast-forward from the merge base af338b16). Every step below changes Montimage/mmt-dpi and is run by a maintainer, in this order. Each step lists its prerequisites, the command, and the check that proves it worked. Before step 1, confirm the gh admin access of AGENT_ENVIRONMENT.md §8 against Montimage/mmt-dpi. The commands run from a clone of the fork with both repositories as remotes:

git remote add upstream git@github.com:Montimage/mmt-dpi.git  # once
git fetch origin && git fetch upstream --tags

State read on 2026-11-07, from GET calls only:

The recorded decisions are in DECISIONS.md (the issue #751 entries).

1. Push release/v1.10.0 to upstream.

2. Re-check #41 after the push.

3. Create the upstream v1.9.1 Release from the fork’s 21 assets.

4. Re-check #41 after the v1.9.1 Release.

5. Close the release alert, upstream issue #42 (and the Install smoke matrix failing issue of step 3, if it was opened).

6. Dismiss the four CodeQL alerts as “Won’t fix”.

7. Enable GitHub Pages (workflow build).

8. Merge #41, never squash or rebase.

9. Require the status checks on main.

10. Tag v1.10.0 (the Release order above, on upstream).

Verify the classification

Check the memory leak

Run the extract_all example under Valgrind on sample pcaps:

cd src/examples
gcc -o extract_all extract_all.c -I /opt/mmt/dpi/include -L /opt/mmt/dpi/lib -lmmt_core -ldl -lpcap
valgrind --leak-check=full --show-reachable=yes ./extract_all -t src/examples/google-fr.pcap

A sample pcap (src/examples/google-fr.pcap) is included for smoke testing.

Clean code

Set a tag for the new version

Tag the release commit on main, then push the tag — that push starts the release workflow, which creates and publishes the GitHub Release (see The release workflow is the only publisher above):

git fetch origin main
git tag -a v1.4 -m "my version 1.4" origin/main
git merge-base --is-ancestor v1.4 origin/main && echo "on main"

Sharing tag:

git push origin v1.4

Checkout a tag:

git checkout -b new_branch_name v1.5

Check the APT repository rebuild

The signed APT repository is built in Montimage/packages, which alone holds the APT signing key (decided in issue #24). This repository only notifies it: the last step of the release job, Notify Montimage/packages (APT repository rebuild) (.github/workflows/release-packages.yml:712-718), runs tools/ci/notify-packages.sh once the Release is published. It sends a repository_dispatch event of type mmt-dpi-release with the tag in its payload ({"tag": "vx.y.z"}) to Montimage/packages, using the repository secret PACKAGES_DISPATCH_TOKEN (issue #76). Re-running the tag run dispatches again, which is harmless: the packages build rebuilds the repository from the Releases each time.

PACKAGES_DISPATCH_TOKEN is a fine-grained token limited to Montimage/packages with Contents: read and write, the permission the dispatches endpoint requires. Contents: write also lets the token push to the unprotected branches of Montimage/packages, not just dispatch; no narrower permission exists for the endpoint. The safeguard is the ruleset on its main branch: pull request, approval and required checks, no force-push, no deletion. Keep that ruleset in place while the token exists.

After the tag run:

  1. Open the step’s log in the Publish GitHub Release job. It reads Dispatched mmt-dpi-release for vx.y.z to Montimage/packages. on success. A ::warning:: titled APT repository not notified means the secret is missing, expired or lacks access; the release itself is not failed by it.
  2. Check that the APT repository workflow (apt-repo.yml) of Montimage/packages started a repository_dispatch run for the tag and that it succeeded:

    gh run list -R Montimage/packages --workflow apt-repo.yml --event repository_dispatch --limit 3
    

If no run started, trigger the rebuild by hand (it rebuilds from the latest Releases, so it needs no tag):

gh workflow run apt-repo.yml -R Montimage/packages

Update the documents


Created by @luongnv89 on 12 July 2016