Releasing a New Version of a KIParla Module

This guide describes the steps to release a new version of any KIParla module (KIP, KIPasti, ParlaTO, ParlaBO) from the dev branch to main.

KIParla follows Semantic Versioning:

  • Patch (x.y.z) — data corrections, typo fixes, metadata updates

  • Minor (x.y.0) — new features, new files, backwards-compatible changes

  • Major (x.0.0) — breaking changes to format or structure

Step 1: Make your changes on dev

All work happens on the dev branch. Make your edits, then commit:

git checkout dev
# ... make changes ...
git add <changed files>
git commit -m "fix: <short description of what was corrected>"
git push origin dev

Step 2: Bump the version in CITATION.cff

Edit CITATION.cff and update the version field to the new version number:

version: x.y.z

Commit the change:

git add CITATION.cff
git commit -m "chore: bump version to x.y.z"
git push origin dev

Step 3: Open a Pull Request from dev to main

On GitHub, open a PR from dev → main with:

  • A descriptive title (e.g. "Release v1.1.1 – normalize Intonation feature values")

  • A summary of what was changed and why

Review the diff, then merge.

Step 4: Run the release workflow

Steps 4 and 5 are fully automated. After merging your PR to main:

  1. Go to Actions → Release Module → Run workflow on GitHub.

  2. Click Run workflow — no inputs needed.

The workflow will:

  1. Read the version from CITATION.cff on main.

  2. Stamp that version into docs/antora.yml (so the Antora version dropdown shows it correctly) and push the change.

  3. Verify the tag does not already exist.

  4. Create and push an annotated tag vx.y.z.

  5. Open a draft GitHub Release pre-filled with auto-generated release notes (commits since the last tag).

Step 5: Review and publish the draft release

Go to Releases on GitHub. You will find a draft named vx.y.z.

  1. Review the auto-generated notes.

  2. Edit, reorder, or add context as needed.

  3. Click Publish release.

Publishing triggers two automated workflows in parallel:

  • notify-collection.yml → rebuilds KIParla-collection (see below).

  • update-changelog.yml → prepends the release notes to the Changelog page in the module documentation, making them available on this site.

Notes

  • Repeat these steps independently for each module that was changed.

  • If multiple modules are released together, keep their version numbers in sync.

  • The CITATION.cff on dev may lag behind main after a release — always verify and update it at the start of a new release cycle.

Make sure the version in CITATION.cff on main is correct before running the release workflow. It reads the version directly and does not prompt for confirmation.

Make sure the version in CITATION.cff on main is correct before running this workflow. The workflow reads it directly and does not prompt for confirmation.

Collection rebuild

Every time a module release is published, the build.yml workflow in KIParla-collection runs automatically. No manual action is required.

What the build workflow does

  1. Clones the latest main of all four module repos (KIP, KIPasti, ParlaBO, ParlaTO).

  2. Syncs all TSV and EAF files into the collection.

  3. Regenerates the linear-jefferson and linear-orthographic formats using tools/tsv2formats.py.

  4. Merges metadata from all modules using tools/merge_metadata.py.

  5. Increments the patch version of the collection in CITATION.cff and updates date-released.

  6. Commits all changes and pushes to main of KIParla-collection.

  7. Creates an annotated tag and GitHub Release for the new collection version, linking back to the module release that triggered the rebuild.

If no files changed (e.g. the module release only updated documentation), no commit or release is created.

Triggering a manual rebuild

You can trigger the collection build at any time without a module release:

gh workflow run build.yml --repo KIParla/KIParla-collection

Or via Actions → Build Collection → Run workflow on GitHub.