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
28 changes: 28 additions & 0 deletions .github/actions/release-please-tools/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
name: Prepare Release Please
description: Use the same pinned action and lockfile for release publication, PRs and tests.
runs:
using: composite
steps:
# Dependabot maintains the action pin in the release workflow. Read its
# lockfile at that same revision so tests and production use the same writer.
- id: action
shell: bash
run: |
pin=$(sed -nE 's|^[[:space:]]*uses: googleapis/release-please-action@([a-f0-9]{40})([[:space:]].*)?$|\1|p' .github/workflows/release-please.yml)
[[ "$pin" =~ ^[a-f0-9]{40}$ ]]
echo "pin=$pin" >> "$GITHUB_OUTPUT"
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
repository: googleapis/release-please-action
ref: ${{ steps.action.outputs.pin }}
path: .release-please-tool
persist-credentials: false
sparse-checkout-cone-mode: false
sparse-checkout: |
/package.json
/package-lock.json
- shell: bash
run: |
mkdir -p "$RUNNER_TEMP/release-please"
cp .release-please-tool/package{,-lock}.json "$RUNNER_TEMP/release-please/"
npm ci --prefix "$RUNNER_TEMP/release-please" --omit=dev --ignore-scripts --no-audit --no-fund
3 changes: 3 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@

<!-- Explain the reasoning, not just the diff. What problem does this solve? -->

<!-- Maintainers: squash-merge using the Conventional Commit PR title. Preserve distinct changes
and BREAKING CHANGE footers in the squash message. Release Please reads that message on main. -->

## Related issue

<!-- Closes #123 — or "none" if this stands alone. -->
Expand Down
35 changes: 35 additions & 0 deletions .github/scripts/pending-comparison.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
"""Lychee config for a Release Please PR whose new tag has not been published."""
import json
import os
import re
import subprocess
import sys
from pathlib import Path


def manifest_tag(content):
version = json.loads(content)["."]
if not re.fullmatch(r"(?:0|[1-9]\d*)(?:\.(?:0|[1-9]\d*)){2}", version):
raise ValueError("Expected a stable release version in the root manifest")
return f"v{version}"


def pending_remap(base, repository):
if not re.fullmatch(r"[a-f0-9]{40}", base):
raise ValueError("Expected the release PR base commit SHA")
manifest = ".release-please-manifest.json"
previous = manifest_tag(subprocess.check_output(["git", "show", f"{base}:{manifest}"]))
pending = manifest_tag(Path(manifest).read_text(encoding="utf-8"))
# Published comparisons always get their ordinary check (including scheduled runs).
if pending == previous or subprocess.run(
["git", "show-ref", "--verify", "--quiet", f"refs/tags/{pending}"]
).returncode == 0:
return []
subprocess.run(["git", "rev-parse", "--verify", f"refs/tags/{previous}^{{commit}}"],
check=True, stdout=subprocess.DEVNULL)
compare = f"https://github.com/{repository}/compare/{previous}..."
return [f"^{re.escape(compare + pending)}$ {compare}{base}"]


if __name__ == "__main__":
print("remap = " + json.dumps(pending_remap(sys.argv[1], os.environ["GITHUB_REPOSITORY"])))
49 changes: 49 additions & 0 deletions .github/scripts/release-notes.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
const { GitHub, Manifest, registerChangelogNotes } = require('release-please');
const { DefaultChangelogNotes } = require('release-please/build/src/changelog-notes/default');
const conventionalPreset = require('conventional-changelog-conventionalcommits');

// GitHub associates both the merge and its source commits with the same PR.
// Prefer the source link for a repeated note. Other PRs, scopes, breaking
// changes and issue references keep their own entries.
function uniqueNotes(commits) {
const notes = new Map();
for (const commit of commits) {
const pr = commit.pullRequest;
const key = JSON.stringify([pr?.number ?? commit.sha, commit.message, commit.notes, commit.references]);
const previous = notes.get(key);
if (!previous || (pr && previous.sha === pr.mergeCommitOid && commit.sha !== previous.sha)) {
notes.set(key, commit);
}
}
return [...notes.values()];
}

// Use the upstream renderer for scopes, issues, escaping and breaking notes.
// Change its template punctuation, never the contributor's Markdown.
async function buildNotes(commits, options) {
const { writerOpts } = await conventionalPreset();
const renderer = new DefaultChangelogNotes({
mainTemplate: writerOpts.mainTemplate
.replace('{{> header}}\n\n', '{{> header}}\n')
.replace('{{/each}}\n\n{{/each}}', '{{/each}}\n{{/each}}')
.replace(/^\* /gm, '- '),
commitPartial: writerOpts.commitPartial.replace(/^\*/, '-')
.replace('[{{shortHash}}]', '[`{{shortHash}}`]'),
});
return renderer.buildNotes(uniqueNotes(commits), options);
}

async function updateReleasePR() {
const [owner, repo] = process.env.GITHUB_REPOSITORY.split('/');
const github = await GitHub.create({ owner, repo, token: process.env.GH_TOKEN });
registerChangelogNotes('default', () => ({ buildNotes }));
const manifest = await Manifest.fromManifest(github, github.repository.defaultBranch,
'release-please-config.json', '.release-please-manifest.json', { skipLabeling: true });
await manifest.createPullRequests();
}

module.exports = { buildNotes };
if (require.main === module) updateReleasePR().catch(error => {
console.error(error.message);
process.exitCode = 1;
});
56 changes: 56 additions & 0 deletions .github/scripts/verify-release-notes.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
const assert = require('node:assert/strict');
const fs = require('node:fs');
const { parseConventionalCommits } = require('release-please/build/src/commit');
const { Changelog } = require('release-please/build/src/updaters/changelog');
const { PullRequestBody } = require('release-please/build/src/util/pull-request-body');
const { buildNotes } = require('./release-notes.cjs');

async function test() {
// Both messages are from PR #25. The abbreviated source SHA also reproduces the Aspell error.
const source = '25e50aee69509511979e2c53b622a6bb89bd0d29';
const merge = 'f86d350b9a56f8e982140c2fc1a51eb606e34b39';
const title = 'fix: improve sidebar quick-access defaults';
const pullRequest = { number: 25, mergeCommitOid: merge, body: '' };
const raw = [
{ sha: merge, message: 'Merge pull request #25 from OWASP/fix/sidebar-quick-access-defaults\n\n' + title, pullRequest },
{ sha: source, message: title, pullRequest },
];
const commits = parseConventionalCommits(raw);
assert.equal(commits.length, 2, 'the merge body and original commit are both parsed');
const options = {
owner: 'OWASP', repository: 'DecodeBox', version: '0.1.1', previousTag: 'v0.1.0', currentTag: 'v0.1.1',
changelogSections: JSON.parse(fs.readFileSync('release-please-config.json'))['changelog-sections'],
};
const first = await buildNotes(commits, options);
assert.equal(first.split('improve sidebar quick-access defaults').length - 1, 1);
assert(first.includes('[`25e50ae`](https://github.com/OWASP/DecodeBox/commit/' + source + ')'));
assert(!first.includes(merge));
const separatePR = { ...raw[1], sha: 'a'.repeat(40), pullRequest: { number: 27, body: '', mergeCommitOid: 'a'.repeat(40) } };
const scoped = await buildNotes(parseConventionalCommits([...raw, separatePR]), options);
assert.equal(scoped.split('improve sidebar quick-access defaults').length - 1, 2, 'distinct PRs retain their notes');
const breaking = { ...raw[0], message: title + '\n\nBREAKING CHANGE: read the new format' };
const distinct = await buildNotes(parseConventionalCommits([breaking, raw[1]]), options);
assert(distinct.includes('read the new format') && distinct.includes(merge) && distinct.includes(source));
const uniqueMerge = { ...raw[0], message: 'fix: resolve a separate integration issue' };
assert((await buildNotes(parseConventionalCommits([uniqueMerge, raw[1]]), options)).includes(merge));

const second = await buildNotes(parseConventionalCommits([
{ sha: 'b'.repeat(40), message: 'feat(ui): add another format\n\nBREAKING CHANGE: use the new format' },
{ sha: 'c'.repeat(40), message: 'fix: retain links\n\nCloses #25' },
]), { ...options, version: '0.2.0', previousTag: 'v0.1.1', currentTag: 'v0.2.0' });
assert(second.includes('BREAKING') && second.includes('### Added') && second.includes('### Fixed'));
assert(second.includes('/issues/25'));
const historical = '# Changelog\n\n## [0.1.0] - 2026-11-20\n\n### Fixed\n\n- A manual entry.\n';
let changelog = historical;
for (const notes of [first, second]) {
const body = PullRequestBody.parse('Proposed release.\n\n---\n\n' + notes + '\n\n---\n\nRelease footer.');
assert.equal(body.releaseData[0].notes, notes);
changelog = new Changelog({ changelogEntry: notes }).updateContent(changelog);
}
assert(changelog.endsWith(historical.slice(historical.indexOf('##'))));
assert(!changelog.includes('\n\n\n') && !/^\* /m.test(changelog));
if (process.argv[2]) fs.writeFileSync(process.argv[2], changelog);
console.log('Release Please merge provenance, Markdown, release body and successive changelog updates passed.');
}

test().catch(error => { console.error(error); process.exitCode = 1; });
50 changes: 47 additions & 3 deletions .github/workflows/docs-quality.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,24 @@ on:
branches: [main]
paths:
- '**.md'
- '.markdownlint.yaml'
- '.markdownlint-cli2.yaml'
- '.github/scripts/**'
- '.github/actions/release-please-tools/**'
- '.github/workflows/docs-quality.yml'
- '.github/workflows/release-please.yml'
- 'release-please-config.json'
- '.spellcheck.yaml'
- '.wordlist.txt'
- '.lycheeignore'
pull_request:
paths:
- '**.md'
- '.markdownlint.yaml'
- '.markdownlint-cli2.yaml'
- '.github/scripts/**'
- '.github/actions/release-please-tools/**'
- '.github/workflows/docs-quality.yml'
- '.github/workflows/release-please.yml'
- 'release-please-config.json'
- '.spellcheck.yaml'
- '.wordlist.txt'
- '.lycheeignore'
Expand Down Expand Up @@ -47,6 +57,22 @@ jobs:
#node_modules
#dist

- name: Prepare the release generator
uses: ./.github/actions/release-please-tools

- name: Exercise the generator against merge history and successive releases
env:
NODE_PATH: ${{ runner.temp }}/release-please/node_modules
run: |
mkdir docs-fixture
cp .markdownlint-cli2.yaml docs-fixture/
node .github/scripts/verify-release-notes.cjs docs-fixture/CHANGELOG.md

- name: Lint the generated changelog with the project configuration
uses: DavidAnson/markdownlint-cli2-action@21c1be1b93ad9ed58fa840aacc3f279cde2a72ff # v24.2.0
with:
globs: docs-fixture/CHANGELOG.md

# Spelling and link rot are advisory rather than blocking. Both depend on
# state outside the repository — a wordlist that has not settled yet, and
# remote hosts that rate-limit CI runners — so a red mark from either is not
Expand Down Expand Up @@ -82,11 +108,29 @@ jobs:
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
fetch-depth: 0

- name: Check a pending release comparison against its base commit
id: preview
if: >-
(github.event_name == 'push' && github.ref == 'refs/heads/main' &&
github.event.before != '0000000000000000000000000000000000000000') ||
(github.event_name == 'pull_request' &&
github.event.pull_request.user.login == 'github-actions[bot]' &&
github.event.pull_request.head.repo.full_name == github.repository &&
github.head_ref == 'release-please--branches--main--components--owasp-decodebox')
env:
BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
run: |
python3 .github/scripts/pending-comparison.py "$BASE_SHA" > "$RUNNER_TEMP/lychee-preview.toml"
echo "args=--config $RUNNER_TEMP/lychee-preview.toml" >> "$GITHUB_OUTPUT"

- name: Check links
uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0
with:
# Mail links are skipped by default; the old --exclude-mail spelling
# was removed upstream and passing it aborts the run before it starts.
args: --no-progress --max-retries 3 './**/*.md'
args: >-
--no-progress --max-retries 4 --retry-wait-time 2 --max-concurrency 8
${{ steps.preview.outputs.args }} './**/*.md'
fail: true
21 changes: 21 additions & 0 deletions .github/workflows/release-please.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,16 @@ jobs:
pull-requests: write

steps:
- name: Check out release tooling
if: inputs.release_tag == ''
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false

- name: Prepare the pinned Release Please library
if: inputs.release_tag == ''
uses: ./.github/actions/release-please-tools

# The pinned action skips labeling new PRs, but requires its pending label
# to update an open PR or publish a merged one. Reconcile its own root PR.
- name: Recognize the pending Release Please PR
Expand Down Expand Up @@ -61,6 +71,7 @@ jobs:
config-file: release-please-config.json
manifest-file: .release-please-manifest.json
skip-labeling: true
skip-github-pull-request: true

- name: Verify the target release
id: target
Expand Down Expand Up @@ -88,6 +99,7 @@ jobs:
with:
ref: refs/tags/${{ steps.target.outputs.tag }}
persist-credentials: false
path: released-source

- name: Set up Node.js
if: steps.target.outputs.tag != ''
Expand All @@ -98,6 +110,7 @@ jobs:

- name: Build the standalone edition
if: steps.target.outputs.tag != ''
working-directory: released-source
run: |
npm clean-install
# Vite embeds the current time. Use the tagged commit time for repeatable HTML.
Expand All @@ -112,6 +125,7 @@ jobs:

- name: Verify and publish the standalone HTML
if: steps.target.outputs.tag != ''
working-directory: released-source
env:
GH_TOKEN: ${{ github.token }}
RELEASE_TAG: ${{ steps.target.outputs.tag }}
Expand All @@ -135,3 +149,10 @@ jobs:
jq -e --arg tag "$RELEASE_TAG" --arg name "$name" --arg digest "$digest" '
.tag_name == $tag and .name == ("OWASP DecodeBox " + $tag) and
any(.assets[]; .name == $name and .state == "uploaded" and .digest == $digest)'

- name: Create or update the Release Please PR
if: inputs.release_tag == ''
env:
GH_TOKEN: ${{ github.token }}
NODE_PATH: ${{ runner.temp }}/release-please/node_modules
run: node .github/scripts/release-notes.cjs
47 changes: 47 additions & 0 deletions .markdownlint-cli2.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
config:
# Relaxed where the default rule fights normal technical writing, strict
# everywhere else. Mirrors the configuration used across OWASP project repos.

no-trailing-punctuation: false
no-inline-html: false
first-line-heading: false
link-fragments: false
table-column-style: false

# MD001 - headings do not have to increment strictly by one level
heading-increment: false

# MD013 - line length
MD013:
line_length: 100
heading_line_length: 100
code_block_line_length: 100
code_blocks: false
headings: true
tables: false
strict: false
stern: true

# MD024 - repeated headings are fine when they sit under different parents
MD024:
siblings_only: true

# MD033 - inline HTML is allowed, but keep it to presentation elements
MD033:
allowed_elements:
- h1
- strong
- p
- img
- a
- br
- details
- summary

# Release Please keeps a change and its commit and issue links on one line.
# Keep every other rule, including list style and spacing, for the changelog.
overrides:
- filter: [CHANGELOG.md]
combine: merge
config:
MD013: false
Loading
Loading