Skip to content
Open
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
105 changes: 105 additions & 0 deletions .github/scripts/publish-release-notes.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
const { execFileSync } = require('node:child_process');

// GitHub supplies first-time status in generated Markdown, not in a structured field.
// Accept its contributor records only, then confirm the PR author and merge via the pulls API.
async function newContributors(repository, previousTag, tag, api, warn) {
let lines;
try {
const { body } = await api('POST', 'releases/generate-notes', {
tag_name: tag, previous_tag_name: previousTag,
});
lines = body.split(/\r?\n/);
} catch {
warn('GitHub contributor metadata is unavailable. Omitting credits.');
return [];
}
const heading = lines.indexOf('## New Contributors');
if (heading < 0) return [];
if (heading !== lines.lastIndexOf('## New Contributors')) {
warn('Ambiguous GitHub contributor section. Omitting credits.');
return [];
}

const credits = [];
const seen = new Set();
for (const line of lines.slice(heading + 1)) {
if (/^#{1,6} |^\*\*Full Changelog/.test(line)) break;
if (!line.trim()) continue;
const match = /^[-*] @([\w-]+(?:\[bot\])?) made their first contribution in (?:https:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/|#)([1-9]\d*)\.?$/.exec(line);
if (!match || (match[2] && match[2] !== repository)) {
warn('Unrecognized GitHub contributor record. Skipping it.');
continue;
}
const [, login, , number] = match;
if (seen.has(login.toLowerCase())) continue;
let pr;
try {
pr = await api('GET', `pulls/${number}`);
} catch {
warn(`Contributor metadata for PR #${number} is unavailable. Skipping it.`);
continue;
}
if (!pr?.merged_at || pr.base?.ref !== 'main' || pr.base.repo?.full_name !== repository ||
pr.user?.login?.toLowerCase() !== login.toLowerCase() || String(pr.number) !== number) {
warn(`Could not confirm the contributor on PR #${number}. Skipping it.`);
continue;
}
seen.add(login.toLowerCase());
credits.push(`- @${pr.user.login} made their first contribution in [#${number}](https://github.com/${repository}/pull/${number}).`);
}
return credits;
}

async function publishReleaseNotes({ created, recoveryTag, tag, id, original, repository }, api, warn = console.warn) {
if (created !== 'true' || recoveryTag || ['v0.1.0', 'v0.1.1'].includes(tag)) return;
if (!/^v\d+\.\d+\.\d+$/.test(tag) || !/^[1-9]\d*$/.test(id)) throw new Error('Invalid new release identity.');

const notes = original.replace(/\r\n/g, '\n').trim();
const [header, ...lines] = notes.split('\n');
const changes = lines.join('\n').trim();
const match = /^## \[(?<version>[\d.]+)\]\((?<comparison>\S+\/compare\/(?<previousTag>v\d+\.\d+\.\d+)\.\.\.v[\d.]+)\) \((?<date>\d{4}-\d{2}-\d{2})\)$/.exec(header);
if (!match || 'v' + match.groups.version !== tag || !changes ||
match.groups.comparison !== `https://github.com/${repository}/compare/${match.groups.previousTag}...${tag}` ||
/^## (?:What's Changed|New Contributors|Standalone Edition)$/m.test(changes)) {
throw new Error('Unrecognized Release Please notes. Leaving the published body intact.');
}
const { comparison, previousTag, date } = match.groups;
const credits = await newContributors(repository, previousTag, tag, api, warn);
const title = `OWASP DecodeBox ${tag}`;
const body = [
`# ${title}`,
`Changes since [${previousTag}](${comparison}) · ${date}`,
"## What's Changed",
changes,
...(credits.length ? ['## New Contributors', credits.join('\n')] : []),
'## Standalone Edition',
`Download \`OWASP-DecodeBox-Standalone-${tag}.html\` from the release assets and open it in your browser.`,
'Core encoding, decoding, and analysis work offline. Processing runs locally in your browser, ' +
'with no installation or server required.',
'Large inputs can pause the tab. Download a new copy for updates and security fixes.',
].join('\n\n');

// Bind the write to the ID returned by createRelease. Protect edits made
// between publication and the end of the standalone build.
const endpoint = `releases/${id}`;
const current = await api('GET', endpoint);
if (current.tag_name !== tag || current.draft || current.body?.replace(/\r\n/g, '\n').trim() !== notes) {
throw new Error('The published release differs from the creation response. Leaving it intact.');
}
const updated = await api('PATCH', endpoint, { name: title, body });
if (updated.tag_name !== tag || updated.name !== title || updated.body !== body) {
throw new Error('GitHub did not confirm the requested release title and body.');
}
return body;
}

module.exports = { publishReleaseNotes };
if (require.main === module) {
const { RELEASE_CREATED: created, RECOVERY_TAG: recoveryTag, RELEASE_TAG: tag, RELEASE_ID: id,
ORIGINAL_NOTES: original, GITHUB_REPOSITORY: repository } = process.env;
const api = (method, path, payload) => JSON.parse(execFileSync('gh', [
'api', '--method', method, `repos/${repository}/${path}`, ...(payload ? ['--input', '-'] : []),
], { input: JSON.stringify(payload), encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 }));
publishReleaseNotes({ created, recoveryTag, tag, id, original, repository }, api)
.catch(error => { console.error(error.message); process.exitCode = 1; });
}
24 changes: 23 additions & 1 deletion .github/scripts/release-notes.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,29 @@ async function buildNotes(commits, options) {
commitPartial: writerOpts.commitPartial.replace(/^\*/, '-')
.replace('[{{shortHash}}]', '[`{{shortHash}}`]'),
});
return renderer.buildNotes(uniqueNotes(commits), options);
const changes = uniqueNotes(commits);
const notes = await renderer.buildNotes(changes, options);
const repo = `${options.host || 'https://github.com'}/${options.owner}/${options.repository}`;
const mergedPRs = new Map(changes
.filter(({ pullRequest: pr }) => pr?.mergeCommitOid && pr.baseBranchName === 'main')
.map(commit => [commit.sha, commit.pullRequest.number]));

// Only annotate citations the renderer kept. A squash subject or issue footer
// can already contain a link to the same PR (GitHub also resolves /issues/N).
const numbers = new Set(mergedPRs.values());
const linked = new Set();
const withPRLinks = notes.replace(/\]\(([^\s)]+)\/(?:pull|issues)\/(\d+)\)/g, (link, host, id) => {
if (host !== repo || !numbers.has(Number(id))) return link;
linked.add(Number(id));
return `](${repo}/pull/${id})`;
});
return withPRLinks.replace(/\[`[0-9a-f]{7}`\]\(([^\s)]+)\/commit\/([0-9a-f]{40})\)/g,
(citation, host, sha) => {
const number = mergedPRs.get(sha);
if (host !== repo || !Number.isSafeInteger(number) || number <= 0 || linked.has(number)) return citation;
linked.add(number);
return `${citation}, [#${number}](${repo}/pull/${number})`;
});
}

async function updateReleasePR() {
Expand Down
93 changes: 92 additions & 1 deletion .github/scripts/verify-release-notes.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,101 @@ 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');
const { publishReleaseNotes } = require('./publish-release-notes.cjs');

// Exercise the actual publication entry point. Only GitHub's HTTP boundary is mocked.
async function testPublication(options) {
const repository = 'OWASP/DecodeBox';
const url = 'https://github.com/' + repository;
function change(message, number, digit) {
const sha = digit.repeat(40);
return { sha, message, pullRequest: { number, mergeCommitOid: sha, baseBranchName: 'main', body: '' } };
}
const optionsFor = version => ({
...options, version, previousTag: 'v0.1.1', currentTag: 'v' + version,
});
const fix = change('fix(ui): restore the folder preference', 31, 'a');
const fixes = await buildNotes(parseConventionalCommits([fix]), optionsFor('0.1.2'));
const changes = await buildNotes(parseConventionalCommits([
fix, change('fix: preserve existing settings', 31, 'b'),
change('feat(data): accept another format\n\nBREAKING CHANGE: update the input format', 32, 'c'),
change('perf: reduce processing time (#33)', 33, 'd'),
change('security: validate imported recipes', 34, 'e'),
change('deps: update the parser', 35, 'f'),
change('docs: update an internal checklist', 36, '1'),
{ sha: '2'.repeat(40), message: 'fix: handle empty files', pullRequest: { number: 39, baseBranchName: 'main', body: '' } },
]), optionsFor('0.2.0'));
const expected = "## What's Changed";
const first = (login, number) => `* @${login} made their first contribution in ${url}/pull/${number}`;
const nativeChanges = `## What's Changed\n* An unrelated label-based title by @regular in ${url}/pull/31\n* Another by @regular in ${url}/pull/33`;
const native = [nativeChanges, '## New Contributors', first('new-user', 32), first('NEW-USER', 32),
first('incorrect', 31), first('new-user', 37).replace(repository, 'another/project'),
first('unavailable', 38), first('another-user', 34), '**Full Changelog**: ...'].join('\n');
async function exercise(original, generated, settings = {}) {
const { releaseData } = PullRequestBody.parse('Proposed release.\n\n---\n\n' + original + '\n\n---\n\nRelease footer.');
const tag = 'v' + releaseData[0].version.toString();
const input = { repository, tag, id: '901', created: 'true', original: releaseData[0].notes, ...settings };
const calls = [], warnings = [];
let saved;
const body = await publishReleaseNotes(input, async (method, path, payload) => {
calls.push([method, path]);
if (method === 'POST' && path === 'releases/generate-notes') {
assert.deepEqual(payload, { previous_tag_name: 'v0.1.1', tag_name: tag });
if (generated instanceof Error) throw generated;
return { body: generated };
}
if (method === 'GET' && path.startsWith('pulls/')) {
const number = Number(path.slice(6));
if (number === 38) throw new Error('unavailable');
const login = { 31: 'regular', 32: 'new-user', 34: 'another-user' }[number];
assert(login, 'unexpected PR lookup');
return { number, merged_at: '2026-11-20', base: { ref: 'main', repo: { full_name: repository } }, user: { login } };
}
assert.equal(path, 'releases/901');
if (method === 'GET') return { tag_name: tag, body: settings.liveBody ?? original, draft: false };
assert.equal(method, 'PATCH');
saved = payload;
return { tag_name: tag, ...payload };
}, warning => warnings.push(warning));
if (body) assert.deepEqual(saved, { name: 'OWASP DecodeBox ' + tag, body });
return { body, calls, warnings };
}
const full = await exercise(changes, native);
const [main, credits] = full.body.split('## New Contributors');
for (const section of ['Added', 'Changed', 'Fixed', 'Security', 'Maintenance']) assert(main.includes('### ' + section));
assert(main.includes('BREAKING CHANGES') && main.includes('update the input format') && main.includes('**data:**'));
assert(main.includes('v0.1.1...v0.2.0') && main.includes('handle empty files') && !main.includes('/pull/39'));
assert(!main.includes('internal checklist') && !main.includes('unrelated label-based title'));
assert.equal(main.split(url + '/pull/31)').length - 1, 1, 'one PR link for two distinct fixes');
assert.equal((main.match(/\[#33\]/g) || []).length, 1, 'squash title already references its PR');
assert(main.includes('[#33](' + url + '/pull/33)'));
assert(credits.includes('@new-user made their first contribution in [#32](' + url + '/pull/32)'));
assert(credits.includes('@another-user') && !credits.includes('@regular') && !credits.includes('@incorrect'));
assert.equal((credits.match(/made their first contribution/g) || []).length, 2);
assert.equal(full.calls.filter(([, path]) => path === 'pulls/32').length, 1);
assert(full.warnings.length > 0 && !full.calls.some(([, path]) => path === 'pulls/37'));
for (const text of [expected, '## New Contributors', '## Standalone Edition']) assert.equal(full.body.split(text).length, 2);
assert(full.body.includes('OWASP-DecodeBox-Standalone-v0.2.0.html') && full.body.includes('open it in your browser'));
assert(full.body.includes('offline') && full.body.includes('locally') && full.body.includes('no installation or server'));
for (const metadata of [nativeChanges, '## New Contributors\n' + first('incorrect', 31), new Error('rate limited'), null]) {
const result = await exercise(fixes, metadata);
assert(result.body.includes('### Fixed') && !result.body.includes('### Added') && !result.body.includes('## New Contributors'));
assert(result.body.includes('OWASP-DecodeBox-Standalone-v0.1.2.html'));
if (typeof metadata !== 'string') assert(result.warnings.length);
}
for (const settings of [{ created: 'false' }, { recoveryTag: 'v0.1.2' }, { tag: 'v0.1.0' }, { tag: 'v0.1.1' }]) {
assert.deepEqual((await exercise(fixes, native, settings)).calls, []);
}
await assert.rejects(exercise(fixes, nativeChanges, { liveBody: 'A maintainer edited these notes.' }), /Leaving it intact/);
return full.body;
}

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 pullRequest = { number: 25, mergeCommitOid: merge, baseBranchName: 'main', 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 },
Expand All @@ -25,6 +113,7 @@ async function test() {
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));
assert.equal(first.split('/pull/25)').length - 1, 1);
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');
Expand All @@ -50,6 +139,8 @@ async function test() {
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);
const release = await testPublication(options);
if (process.argv[3]) fs.writeFileSync(process.argv[3], release + '\n');
console.log('Release Please merge provenance, Markdown, release body and successive changelog updates passed.');
}

Expand Down
10 changes: 6 additions & 4 deletions .github/workflows/docs-quality.yml
Original file line number Diff line number Diff line change
Expand Up @@ -64,14 +64,16 @@ jobs:
env:
NODE_PATH: ${{ runner.temp }}/release-please/node_modules
run: |
mkdir docs-fixture
mkdir -p docs-fixture/release
cp .markdownlint-cli2.yaml docs-fixture/
node .github/scripts/verify-release-notes.cjs docs-fixture/CHANGELOG.md
cp .markdownlint-cli2.yaml docs-fixture/release/
# Published notes contain the same long commit citations as the changelog.
node .github/scripts/verify-release-notes.cjs docs-fixture/CHANGELOG.md docs-fixture/release/CHANGELOG.md

- name: Lint the generated changelog with the project configuration
- name: Lint the generated changelog and final release body
uses: DavidAnson/markdownlint-cli2-action@21c1be1b93ad9ed58fa840aacc3f279cde2a72ff # v24.2.0
with:
globs: docs-fixture/CHANGELOG.md
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
Expand Down
21 changes: 17 additions & 4 deletions .github/workflows/release-please.yml
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,8 @@ jobs:
RELEASE_TAG: ${{ steps.release.outputs.tag_name || inputs.release_tag }}
RELEASE_VERSION: ${{ steps.release.outputs.version }}
run: |
if [[ ! "$RELEASE_TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ || "$RELEASE_TAG" == v0.1.0 ]]; then
echo "::error::Expected a stable vX.Y.Z tag other than the preserved first release."
if [[ ! "$RELEASE_TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ || "$RELEASE_TAG" == v0.1.0 || "$RELEASE_TAG" == v0.1.1 ]]; then
echo "::error::Expected a stable vX.Y.Z tag after the two preserved releases."
exit 1
fi
if [[ -n "$RELEASE_VERSION" && "$RELEASE_TAG" != "v$RELEASE_VERSION" ]]; then
Expand Down Expand Up @@ -144,12 +144,25 @@ jobs:
cp dist/decodebox.html "$ASSET_PATH"
digest="sha256:$(sha256sum "$ASSET_PATH" | cut -d' ' -f1)"
gh release upload "$RELEASE_TAG" "$ASSET_PATH" --clobber
gh release edit "$RELEASE_TAG" --title "OWASP DecodeBox $RELEASE_TAG"
gh api "repos/$GH_REPO/releases/tags/$RELEASE_TAG" | \
jq -e --arg tag "$RELEASE_TAG" --arg name "$name" --arg digest "$digest" '
.tag_name == $tag and .name == ("OWASP DecodeBox " + $tag) and
.tag_name == $tag and
any(.assets[]; .name == $name and .state == "uploaded" and .digest == $digest)'

# Finish a new description even if an asset needs a later manual rebuild.
- name: Format the newly created GitHub Release
if: >-
!cancelled() && inputs.release_tag == '' && steps.release.outputs.release_created == 'true' &&
steps.target.outcome == 'success'
env:
GH_TOKEN: ${{ github.token }}
RELEASE_CREATED: ${{ steps.release.outputs.release_created }}
RECOVERY_TAG: ${{ inputs.release_tag }}
RELEASE_TAG: ${{ steps.release.outputs.tag_name }}
RELEASE_ID: ${{ steps.release.outputs.id }}
ORIGINAL_NOTES: ${{ steps.release.outputs.body }}
run: node .github/scripts/publish-release-notes.cjs

- name: Create or update the Release Please PR
if: inputs.release_tag == ''
env:
Expand Down
Loading