Support monorepo releases with component changelog files #78

Open
opened 2026-11-08 20:24:09 +00:00 by martin · 1 comment
Owner

Summary

Extend forgejo-release to accept a configurable CHANGELOG.md file as the source of Forgejo release notes, allowing independently released components in a monorepo to publish only their own changes. CI promotes the component’s Unreleased section into the new release by updating its heading with the version from the tag and the release date. Only that newly released section becomes the Forgejo release body.

Context

The plugin currently generates release notes from Conventional Commits. It selects the previous tag by semantic version and matching prefix, but the commit range is repository-wide: prefix matching does not filter changes by component. See plugins/forgejo-release/README.md and plugins/forgejo-release/src/main.rs.

The requested alternative is a maintained changelog for each component, selected by file path in the CI workspace. The changelog should supply the release body rather than mixing in unrelated repository changes.

Scope

  • Add an optional configurable changelog path, including paths such as plugins/<name>/CHANGELOG.md.
  • Resolve the released component and version from the CI tag using configurable rules.
  • Promote the selected component’s Unreleased section to a versioned, dated release section, retaining a fresh empty Unreleased section for future changes.
  • Publish only that new release section, preserving its nested headings and Markdown; never publish or attach the entire changelog.
  • Provide a documented CI flow that stamps the intended changelog entry with the release version and date before publishing its notes. Keep release-note consumption and changelog preparation responsibilities explicit.
  • Preserve the existing Conventional Commit behavior when no changelog is configured and the existing rules for draft versus published releases.
  • Add tests and a monorepo workflow example.

Acceptance criteria

  • A CI release resolves the component and version from the tag and selects the corresponding changelog in the checked-out workspace.
  • For ntfy-v0.3.1, all notes under Unreleased in plugins/ntfy/CHANGELOG.md become the new 0.3.1 section, with its heading stamped with the release date and an empty Unreleased section retained. The version is taken from the tag, not calculated by bumping a historical entry.
  • The Forgejo release body contains only the newly created version/date heading and its content, including nested headings. File-level text, the empty Unreleased section, other versions, and other components’ notes are excluded; the file is not attached.
  • A fixture with two independently released components demonstrates that releasing one includes neither the other component's notes nor historical entries.
  • The documented CI preparation flow stamps the intended entry with the release version and date while preserving other entries and Markdown content.
  • Supported changelog headings, release-entry selection, component-prefixed tag/version mapping, and date format/timezone are documented and tested.
  • Missing or unreadable configured files and missing or ambiguous release entries fail with actionable diagnostics before publishing a release.
  • Re-running preparation reuses an existing section for the target version without duplicating it, changing its stamped date, or consuming new Unreleased notes. Published releases remain protected by the existing failure behavior. Retry behavior and persistence requirements are documented and tested.
  • Without a changelog setting, existing Conventional Commit generation and release-state behavior remain unchanged.
  • Documentation shows the settings and ordering of changelog preparation and release publication, and explains whether/how the updated file is persisted to Git.

Configuration and behavior examples

The following settings and image are illustrative proposals, not currently available functionality. Replace the image placeholder with a published version that implements this feature. Authentication uses the existing settings/environment fallbacks; tokens are supplied through CI secrets.

This repository: independently released plugins

A generic step can be added after the existing OCI build/push step in .woodpecker/release.yaml:

when:
  event: tag
  ref: refs/tags/*-v*

steps:
  - name: Publish Forgejo release
    image: "registry.example.com/woodpecker-plugin-forgejo-release:<version-with-changelog-support>"
    settings:
      forgejo_url: https://code.martials.no
      forgejo_token:
        from_secret: forge_token
      tag_pattern: "{component}-v{version}"
      changelog: "plugins/{component}/CHANGELOG.md"

tag_pattern describes how to extract the component and semantic version from CI_COMMIT_TAG; changelog resolves the input path relative to the CI workspace. These are plugin placeholders, not shell environment interpolation. Component names can contain hyphens, including forgejo-release; matching must be unambiguous and resolved paths must remain within the workspace.

CI tag Component Version Changelog
ntfy-v0.3.1 ntfy 0.3.1 plugins/ntfy/CHANGELOG.md
forgejo-release-v0.2.0 forgejo-release 0.2.0 plugins/forgejo-release/CHANGELOG.md

For ntfy-v0.3.1, the flow is:

  1. Match the tag and resolve plugins/ntfy/CHANGELOG.md; do not infer the component from changed files.
  2. Validate the selected file and release sections before any publication.
  3. Promote its Unreleased notes to 0.3.1 and stamp the release date, or reuse an existing 0.3.1 section on a preparation retry.
  4. Create the Forgejo release named/tagged ntfy-v0.3.1 (or update an existing draft according to current behavior), using only the 0.3.1 section as its body.
  5. Leave other components’ changelogs and prior releases unchanged.

Single-component repository

For tags such as v0.3.1, use a fixed changelog path and no component placeholder:

# Proposed settings within the release step; same authentication as above.
settings:
  tag_pattern: "v{version}"
  changelog: "CHANGELOG.md"

Changelog transformation and published notes

Before releasing ntfy-v0.3.1:

# Changelog

## [Unreleased]
### Fixed
- Handle empty messages.

## [0.3.0] - 2026-11-08
### Added
- Support for notification priorities.

After CI preparation (assuming a release date of 2026-11-09 for this example):

# Changelog

## [Unreleased]

## [0.3.1] - 2026-11-09
### Fixed
- Handle empty messages.

## [0.3.0] - 2026-11-08
### Added
- Support for notification priorities.

The complete Forgejo release body is only:

## [0.3.1] - 2026-11-09
### Fixed
- Handle empty messages.

Extraction stops at the next release-level heading, not nested headings such as ### Fixed.

Persistence and tag timing

The examples describe workspace preparation and release publication, not automatic Git commits or pushes. This repository’s current pipeline runs after just release creates the tag, so changing a workspace file cannot alter the tagged commit. Decide explicitly whether to persist the stamped changelog after publication or add a pre-tag preparation phase if it must be included in the tagged commit. Never move an existing tag. Retries in a fresh workspace need access to any previously persisted/stamped state to retain the original date; this must be covered by the chosen persistence design.

Dependencies

  • Related: #64 proposes generic Forgejo file synchronization and could be reused if CI needs to persist changelog changes. It is not an established prerequisite.

Design decisions to resolve

  • Exact supported heading syntax and behavior for an empty Unreleased section. Promotion of Unreleased into the tagged version is confirmed; existing versioned sections are reused for retries, not the source for a new version.
  • Final setting names and tag-pattern/template syntax. The examples above are proposals.
  • Date source and timezone; the examples propose YYYY-MM-DD in UTC, not a fixed release date.
  • Whether stamping belongs in a preparation mode of this plugin or a separate CI step/tool.
  • Whether CI updates only its workspace or commits the changelog back to the repository, and how that relates to the tagged commit. Do not silently retarget existing tags or assume push permissions.
## Summary Extend `forgejo-release` to accept a configurable `CHANGELOG.md` file as the source of Forgejo release notes, allowing independently released components in a monorepo to publish only their own changes. CI promotes the component’s `Unreleased` section into the new release by updating its heading with the version from the tag and the release date. Only that newly released section becomes the Forgejo release body. ## Context The plugin currently generates release notes from Conventional Commits. It selects the previous tag by semantic version and matching prefix, but the commit range is repository-wide: prefix matching does not filter changes by component. See `plugins/forgejo-release/README.md` and `plugins/forgejo-release/src/main.rs`. The requested alternative is a maintained changelog for each component, selected by file path in the CI workspace. The changelog should supply the release body rather than mixing in unrelated repository changes. ## Scope - Add an optional configurable changelog path, including paths such as `plugins/<name>/CHANGELOG.md`. - Resolve the released component and version from the CI tag using configurable rules. - Promote the selected component’s `Unreleased` section to a versioned, dated release section, retaining a fresh empty `Unreleased` section for future changes. - Publish only that new release section, preserving its nested headings and Markdown; never publish or attach the entire changelog. - Provide a documented CI flow that stamps the intended changelog entry with the release version and date before publishing its notes. Keep release-note consumption and changelog preparation responsibilities explicit. - Preserve the existing Conventional Commit behavior when no changelog is configured and the existing rules for draft versus published releases. - Add tests and a monorepo workflow example. ## Acceptance criteria - [ ] A CI release resolves the component and version from the tag and selects the corresponding changelog in the checked-out workspace. - [ ] For `ntfy-v0.3.1`, all notes under `Unreleased` in `plugins/ntfy/CHANGELOG.md` become the new `0.3.1` section, with its heading stamped with the release date and an empty `Unreleased` section retained. The version is taken from the tag, not calculated by bumping a historical entry. - [ ] The Forgejo release body contains only the newly created version/date heading and its content, including nested headings. File-level text, the empty `Unreleased` section, other versions, and other components’ notes are excluded; the file is not attached. - [ ] A fixture with two independently released components demonstrates that releasing one includes neither the other component's notes nor historical entries. - [ ] The documented CI preparation flow stamps the intended entry with the release version and date while preserving other entries and Markdown content. - [ ] Supported changelog headings, release-entry selection, component-prefixed tag/version mapping, and date format/timezone are documented and tested. - [ ] Missing or unreadable configured files and missing or ambiguous release entries fail with actionable diagnostics before publishing a release. - [ ] Re-running preparation reuses an existing section for the target version without duplicating it, changing its stamped date, or consuming new `Unreleased` notes. Published releases remain protected by the existing failure behavior. Retry behavior and persistence requirements are documented and tested. - [ ] Without a changelog setting, existing Conventional Commit generation and release-state behavior remain unchanged. - [ ] Documentation shows the settings and ordering of changelog preparation and release publication, and explains whether/how the updated file is persisted to Git. ## Configuration and behavior examples The following settings and image are illustrative proposals, not currently available functionality. Replace the image placeholder with a published version that implements this feature. Authentication uses the existing settings/environment fallbacks; tokens are supplied through CI secrets. ### This repository: independently released plugins A generic step can be added after the existing OCI build/push step in `.woodpecker/release.yaml`: ```yaml when: event: tag ref: refs/tags/*-v* steps: - name: Publish Forgejo release image: "registry.example.com/woodpecker-plugin-forgejo-release:<version-with-changelog-support>" settings: forgejo_url: https://code.martials.no forgejo_token: from_secret: forge_token tag_pattern: "{component}-v{version}" changelog: "plugins/{component}/CHANGELOG.md" ``` `tag_pattern` describes how to extract the component and semantic version from `CI_COMMIT_TAG`; `changelog` resolves the input path relative to the CI workspace. These are plugin placeholders, not shell environment interpolation. Component names can contain hyphens, including `forgejo-release`; matching must be unambiguous and resolved paths must remain within the workspace. | CI tag | Component | Version | Changelog | | --- | --- | --- | --- | | `ntfy-v0.3.1` | `ntfy` | `0.3.1` | `plugins/ntfy/CHANGELOG.md` | | `forgejo-release-v0.2.0` | `forgejo-release` | `0.2.0` | `plugins/forgejo-release/CHANGELOG.md` | For `ntfy-v0.3.1`, the flow is: 1. Match the tag and resolve `plugins/ntfy/CHANGELOG.md`; do not infer the component from changed files. 2. Validate the selected file and release sections before any publication. 3. Promote its `Unreleased` notes to `0.3.1` and stamp the release date, or reuse an existing `0.3.1` section on a preparation retry. 4. Create the Forgejo release named/tagged `ntfy-v0.3.1` (or update an existing draft according to current behavior), using only the `0.3.1` section as its body. 5. Leave other components’ changelogs and prior releases unchanged. ### Single-component repository For tags such as `v0.3.1`, use a fixed changelog path and no component placeholder: ```yaml # Proposed settings within the release step; same authentication as above. settings: tag_pattern: "v{version}" changelog: "CHANGELOG.md" ``` ### Changelog transformation and published notes Before releasing `ntfy-v0.3.1`: ```markdown # Changelog ## [Unreleased] ### Fixed - Handle empty messages. ## [0.3.0] - 2026-11-08 ### Added - Support for notification priorities. ``` After CI preparation (assuming a release date of `2026-11-09` for this example): ```markdown # Changelog ## [Unreleased] ## [0.3.1] - 2026-11-09 ### Fixed - Handle empty messages. ## [0.3.0] - 2026-11-08 ### Added - Support for notification priorities. ``` The complete Forgejo release body is only: ```markdown ## [0.3.1] - 2026-11-09 ### Fixed - Handle empty messages. ``` Extraction stops at the next release-level heading, not nested headings such as `### Fixed`. ### Persistence and tag timing The examples describe workspace preparation and release publication, not automatic Git commits or pushes. This repository’s current pipeline runs after `just release` creates the tag, so changing a workspace file cannot alter the tagged commit. Decide explicitly whether to persist the stamped changelog after publication or add a pre-tag preparation phase if it must be included in the tagged commit. Never move an existing tag. Retries in a fresh workspace need access to any previously persisted/stamped state to retain the original date; this must be covered by the chosen persistence design. ## Dependencies - Related: #64 proposes generic Forgejo file synchronization and could be reused if CI needs to persist changelog changes. It is not an established prerequisite. ## Design decisions to resolve - Exact supported heading syntax and behavior for an empty `Unreleased` section. Promotion of `Unreleased` into the tagged version is confirmed; existing versioned sections are reused for retries, not the source for a new version. - Final setting names and tag-pattern/template syntax. The examples above are proposals. - Date source and timezone; the examples propose `YYYY-MM-DD` in UTC, not a fixed release date. - Whether stamping belongs in a preparation mode of this plugin or a separate CI step/tool. - Whether CI updates only its workspace or commits the changelog back to the repository, and how that relates to the tagged commit. Do not silently retarget existing tags or assume push permissions.
Author
Owner

Decisions

  • User clarification: the Forgejo release body must contain only the changelog section belonging to that release, not the entire CHANGELOG.md file. The file is the input source, not a release attachment.
  • Exclude the file-level introduction, other release sections, and unrelated Unreleased content. Preserve nested headings and Markdown within the selected release section. If preparation promotes Unreleased, publish only the resulting section for the target version.

Design

Component recognition remains a proposal: for this repository, derive the component and version from <component>-v<version> and resolve plugins/<component>/CHANGELOG.md. A configurable tag pattern and changelog path template were suggested, but have not been selected as implemented settings.

## Decisions - User clarification: the Forgejo release body must contain only the changelog section belonging to that release, not the entire `CHANGELOG.md` file. The file is the input source, not a release attachment. - Exclude the file-level introduction, other release sections, and unrelated `Unreleased` content. Preserve nested headings and Markdown within the selected release section. If preparation promotes `Unreleased`, publish only the resulting section for the target version. ## Design Component recognition remains a proposal: for this repository, derive the component and version from `<component>-v<version>` and resolve `plugins/<component>/CHANGELOG.md`. A configurable tag pattern and changelog path template were suggested, but have not been selected as implemented settings.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/woodpecker-plugins#78
No description provided.