Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ _None_

### New Features

_None_
- Add `generate_release_notes_file` to write generated GitHub notes into a `RELEASE-NOTES.txt` or Markdown `CHANGELOG.md` version section in existing release lanes. [#776]

### Bug Fixes

_None_
- Pass the configured release notes path to GitHub using the expected `configuration_file_path` parameter. [#776]

### Internal Changes

Expand Down
31 changes: 29 additions & 2 deletions docs/Release Notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ Release notes are an important part of the release process and we aim to provide
2. _translating them_, so that more people are able to get them.


## Release notes workflow
## Manually maintained release notes workflow

1. In the root folder of every project, we maintain a `RELEASE-NOTES.txt` file that is updated by every PR that adds a relevant feature. As a reminder to developers and reviewers, we usually add a note about this in the project GitHub PR template.
1. In the root folder of every project that adopts this approach, we maintain a `RELEASE-NOTES.txt` file that is updated by every PR that adds a relevant feature. As a reminder to developers and reviewers, we usually add a note about this in the project GitHub PR template.
2. During code freeze, the `code_freeze` lane of the project's `Fastfile` typically calls at some point:
- The `extract_release_notes_for_version` action, to extract just the release notes of the version being code-frozen in a separate file (e.g. `WordPress/Resources/release_notes.txt`).
- Then the `{ios|android}_update_release_notes` action is then used to add a new empty section at the top of the `RELEASE-NOTES.txt` file, ready for the next version.
Expand All @@ -17,3 +17,30 @@ Release notes are an important part of the release process and we aim to provide
6. At the end of the beta testing, the `gp_downloadmetadata` action is used to download the translation for the release notes and the other relevant metadata from GlotPress, and update the `fastlane/metadata/{locale}/release_notes.txt` files in fastlane's dedicated folder—ready to be used by `deliver`/`supply` which will take care of using the Apple and Google APIs to upload them in App Store Connect / Play Store Console.

_Note:_ All these actions need some not-trivial configuration, so it’s usually best to add dedicated lanes in the project and use them to invoke the actions.


## Generate notes from pull requests at release time

Projects can use `generate_release_notes_file` during code freeze or release preparation instead of editing a shared file in every feature PR. PR titles provide the draft text, and a GitHub release-notes configuration controls which labels are included and how changes are grouped.

The default `format: :release_notes` uses the existing underlined version headings in `RELEASE-NOTES.txt`. To update a Markdown changelog, select the format and path explicitly:

```ruby
generate_release_notes_file(
repository: 'owner/repository',
version: '1.2.0',
tag_name: '1.2.0',
previous_tag: '1.1.0',
target_commitish: 'trunk',
configuration_file_path: '.github/release.yml',
format: :changelog,
release_notes_file_path: 'CHANGELOG.md',
dry_run: true
)
```

Changelog format uses numeric `## <version>` headings, such as `## 1.2.0`, with generated headings nested beneath them. The existing file must have at least one such version section. Introductions, `## Trunk`/`## Unreleased`, and other versions are preserved. A new version is inserted before the first version section; an existing version's entire section is replaced. Pending entries are not automatically moved into the generated version.

Each call writes one file. Projects wanting both files can call the action twice, choosing a configuration for each audience: a developer changelog may include internal changes that store-oriented notes exclude. `format` does not choose a filename or change GitHub filtering. Linked version headings, dates in version headings, and prerelease headings are not supported. Use `#` headings throughout the changelog: underlined Markdown headings are not recognized as section boundaries. Unterminated code fences or HTML comments cause the action to fail without writing.

Use `dry_run: true` to preview, then omit it to write the draft. The action does not commit files. Keep the explicit previous tag and a published target commit; GitHub uses an existing `tag_name` in preference to `target_commitish`. Review the generated text before publishing, and regenerate only before editorial changes because generation replaces the requested version's contents. The existing `extract_release_notes_for_version` action supports the underlined format only.
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# frozen_string_literal: true

require 'fastlane/action'
require_relative 'get_prs_between_tags'
require_relative '../../helper/release_notes_helper'

module Fastlane
module Actions
class GenerateReleaseNotesFileAction < Action
def self.run(params)
UI.user_error!('An explicit previous_tag is required to generate release notes') if params[:previous_tag].to_s.empty?
version = params[:version]
UI.user_error!('Expected a numeric release version') unless version.match?(/\A\d+(?:\.\d+){0,2}\z/)

path = params[:release_notes_file_path]
contents = File.read(path)
format = params[:format]
options = params.values.except(*custom_options.map(&:key))
markdown = other_action.get_prs_between_tags(**options, fail_on_error: true)
section = Helper::ReleaseNotesHelper.format_section(version: version, markdown: markdown, format: format)
updated = Helper::ReleaseNotesHelper.update_section(contents: contents, version: version, section: section, format: format)

if params[:dry_run]
UI.message(section)
else
File.write(path, updated)
end
section
end

def self.description
'Write generated GitHub notes to a release notes or Markdown changelog version section'
end

def self.details
<<~DETAILS
Inserts or replaces one version section using get_prs_between_tags, preserving other versions and header comments.
Defaults to the underlined version headings used in RELEASE-NOTES.txt.
Use format: :changelog and release_notes_file_path: 'CHANGELOG.md' for numeric ## version headings.
Changelog output nests generated headings beneath the version and preserves Trunk/Unreleased sections.
The existing file must contain at least one version section in the selected format.
Keeps authors, contributors, and links. Does not promote Unreleased entries or edit other versions.
Use configuration_file_path to exclude or group PRs by GitHub labels; no title markers are needed.
For a separate report, such as release testing, call get_prs_between_tags with its own configuration_file_path.
Requires an explicit previous_tag and a published target_commitish if tag_name does not exist.
Use dry_run to preview without writing. Does not commit changes.
DETAILS
end

def self.available_options
GetPrsBetweenTagsAction.available_options.reject { |option| option.key == :fail_on_error } + custom_options
end

def self.custom_options
[
FastlaneCore::ConfigItem.new(key: :version, description: 'Numeric version heading in the output file', type: String),
FastlaneCore::ConfigItem.new(key: :release_notes_file_path, description: 'Existing release notes file', type: String, default_value: 'RELEASE-NOTES.txt'),
FastlaneCore::ConfigItem.new(key: :format,
description: 'Version section format: :release_notes or :changelog',
type: Symbol,
default_value: :release_notes,
verify_block: proc do |value|
UI.user_error!('format must be :release_notes or :changelog') unless %i[release_notes changelog].include?(value)
end),
FastlaneCore::ConfigItem.new(key: :dry_run, description: 'Preview the section without writing the file', type: Boolean, default_value: false),
]
end

private_class_method :custom_options

def self.return_value
'The generated version section'
end

def self.authors
['Automattic']
end

def self.is_supported?(platform)
true
end
end
end
end
Original file line number Diff line number Diff line change
Expand Up @@ -311,7 +311,7 @@ def generate_release_notes(repository:, tag_name:, previous_tag:, target_commiti
tag_name: tag_name,
target_commitish: target_commitish, # Only used if no git tag named `tag_name` exists yet
previous_tag_name: previous_tag,
config_file_path: config_file_path
configuration_file_path: config_file_path

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked in the docs at https://docs.github.com/en/rest/releases/releases?apiVersion=2026-03-10#generate-release-notes-content-for-a-release and confirm configuration_file_path is the right name.

Not sure by what magic it was working before. Or maybe the GitHub API changed it but kept support for the old name for compatibility?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed, yeah, can be. I was surprised it works (or worked?) 🤔

)
res.body
end
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,101 @@
module Fastlane
module Helper
module ReleaseNotesHelper
VERSION_HEADING = /^\d+(?:\.\d+){0,2}\r?\n[-=]+(?:\r?\n|\z)/

# Render a version section, nesting generated Markdown headings in changelog output.
def self.format_section(version:, markdown:, format: :release_notes)
return "#{version}\n-----\n#{markdown.rstrip}\n\n" unless format == :changelog

headings = markdown_headings(markdown)
shift = [3 - (headings.map(&:last).min || 3), 0].max
markdown = markdown.dup
headings.reverse_each do |offset, level|
markdown.insert(markdown.index('#', offset), '#' * [shift, 6 - level].min)
end
"## #{version}\n\n#{markdown.rstrip}\n\n"
end

# Insert or replace one version, preserving other sections and line endings.
# @param [String] contents Existing release notes or changelog contents.
# @param [String] version The section to replace or insert.
# @param [String] section The generated version section.
# @param [Symbol] format Version heading format: :release_notes or :changelog.
# @return [String] Updated file contents.
def self.update_section(contents:, version:, section:, format: :release_notes)
if format == :changelog
offsets = markdown_headings(contents).select { |_, level| level <= 2 }.map(&:first)
sections = [0, *offsets, contents.length].uniq.each_cons(2).map { |start, finish| contents[start...finish] }
versions = sections.map { |part| part.lines.first[/\A {0,3}##[ \t]+(\d+(?:\.\d+){0,2})[ \t]*\r?\n?\z/, 1] }
else
sections = contents.split(/(?=#{VERSION_HEADING})/)
versions = sections.map { |part| part.lines.first.chomp if part.match?(VERSION_HEADING) }
end
first_version = versions.index { |value| value }
UI.user_error!('No version headings found in the release notes file') unless first_version
UI.user_error!("Duplicate release notes sections for #{version}") if versions.count(version) > 1

newline = contents.include?("\r\n") ? "\r\n" : "\n"
section = section.gsub(/\r?\n/, newline)
index = versions.index(version)
if index
sections[index] = section
else
sections.insert(first_version, section)
end
sections.join
end

# Return line offsets and levels of ATX headings, ignoring code fences and HTML comments.
def self.markdown_headings(contents)
headings = []
fence = nil
html_comment = false
offset = 0
contents.each_line do |line|
if fence
fence = nil if line.match?(/\A {0,3}#{Regexp.escape(fence[0])}{#{fence.length},}[ \t]*\r?\n?\z/)
elsif !html_comment && (match = line.match(/\A {0,3}(`{3,}(?!.*`)|~{3,})/))
fence = match[1]
else
if !html_comment && (match = line.match(/\A {0,3}(\#{1,6})(?:[ \t]+|\r?\n?\z)/))
headings << [offset, match[1].length]
end
html_comment = html_comment_open?(line, open: html_comment) unless !html_comment && line.match?(/\A(?: {4}| {0,3}\t)/)
end
offset += line.length
end
UI.user_error!('Unterminated code fence in Markdown release notes') if fence
UI.user_error!('Unterminated HTML comment in Markdown release notes') if html_comment
headings
end
private_class_method :markdown_headings

# Track comment delimiters in order, skipping matched inline code spans.
def self.html_comment_open?(line, open:)
cursor = 0
loop do
if open
closing = line.index('-->', cursor)
return true unless closing

cursor = closing + 3
open = false
else
marker = line.match(/<!--|`+/, cursor)
return false unless marker

cursor = marker.end(0)
if marker[0] == '<!--'
open = true
elsif (closing = line.match(/(?<!`)#{Regexp.escape(marker[0])}(?!`)/, cursor))
cursor = closing.end(0)
end
end
end
end
private_class_method :html_comment_open?

# Update the release notes file (typycally RELEASE-NOTES.txt) to add a new entry.
#
# @param [String] path The path to the release notes text file.
Expand Down
Loading