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
70 changes: 70 additions & 0 deletions .github/scripts/public_api.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
// Prints the public surface of a JavaScript SDK module as sorted "<path> <kind>" lines, so two versions can be compared.
// Usage: node public_api.mjs <module file> <name>=<expression> [<name>=<expression> ...]
// Each expression is evaluated with `sdk` bound to the module's export and is listed under its name, for example
// Countly=sdk or Instance='new sdk.CountlyClass({ app_key: "key", url: "https://example.invalid" })'.
import { writeSync } from "node:fs";
import { pathToFileURL } from "node:url";
import { resolve } from "node:path";

const MAX_DEPTH = 4;

/**
* Returns the kind printed for a value: its typeof, with null and arrays told apart.
* @param {*} value the value to describe
* @returns {string} "null", "array" or the typeof of the value
*/
function kindOf(value) {
if (value === null) {
return "null";
}
return Array.isArray(value) ? "array" : typeof value;
}

/**
* Adds a line for the value at path and, for objects and functions, for each public member below it.
* Names that start with an underscore are private by convention and skipped, and array elements are data.
* @param {*} value the value to describe
* @param {string} path the dotted path that reaches the value
* @param {string[]} lines the lines collected so far
* @param {WeakSet<object>} seen the objects already described, so cycles end
* @param {number} depth how many members deep the value is
*/
function describe(value, path, lines, seen, depth) {
const kind = kindOf(value);
lines.push(`${path} ${kind}`);
if ((kind !== "object" && kind !== "function") || depth >= MAX_DEPTH || seen.has(value)) {
return;
}
seen.add(value);
for (const key of Object.keys(value)) {
if (!key.startsWith("_")) {
describe(value[key], `${path}.${key}`, lines, seen, depth + 1);
}
}
if (kind === "function" && value.prototype) {
for (const key of Object.getOwnPropertyNames(value.prototype)) {
if (key !== "constructor" && !key.startsWith("_")) {
lines.push(`${path}.prototype.${key} ${kindOf(value.prototype[key])}`);
}
}
}
}

const [modulePath, ...roots] = process.argv.slice(2);
if (!modulePath || roots.length === 0) {
console.error("Usage: node public_api.mjs <module file> <name>=<expression> [...]");
process.exit(2);
}
const loaded = await import(pathToFileURL(resolve(modulePath)).href);
const sdk = loaded.default ?? loaded;
const lines = [];
for (const root of roots) {
const separator = root.indexOf("=");
const name = root.slice(0, separator);
const value = new Function("sdk", `return (${root.slice(separator + 1)});`)(sdk);
describe(value, name, lines, new WeakSet(), 0);
}
// A synchronous write, because the exit below would cut off an asynchronous write to a pipe.
writeSync(1, [...new Set(lines)].sort().join("\n") + "\n");
// The SDK may have started timers (an instance's heartbeat, for example), so the process ends here.
process.exit(0);
37 changes: 37 additions & 0 deletions .github/scripts/public_api_record.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
#!/usr/bin/env bash
# Compares the public API this run extracted with the record committed in the repository. On a difference it lists the
# changed lines in the job summary, copies the extracted API to $RUNNER_TEMP/public-api-record/ under the record's path,
# for the workflow to upload, and fails: a deliberate change is committed together with a changelog line.
# $@ pairs "<extracted file>=<record path>"
set -euo pipefail
out="$RUNNER_TEMP/public-api-record"
status=0
current="$RUNNER_TEMP/public-api-current.txt"
recorded="$RUNNER_TEMP/public-api-recorded.txt"
for pair in "$@"; do
extracted=${pair%%=*}
record=${pair#*=}
# Line endings do not count: .NET writes CRLF on Windows, and a Windows checkout can give the record CRLF too.
tr -d '\r' < "$extracted" > "$current"
if [ -f "$record" ] && tr -d '\r' < "$record" | cmp -s - "$current"; then
echo "The public API is the one $record records."
continue
fi
status=1
mkdir -p "$out/$(dirname "$record")"
cp "$current" "$out/$record"
{
printf '### The public API differs from %s\n\n' "$record"
printf "Commit \`%s\` from the \`public-api-record\` artifact of this run, with a changelog line for the change.\n\n" "$record"
if [ -f "$record" ]; then
printf '```diff\n'
tr -d '\r' < "$record" > "$recorded"
diff -u "$recorded" "$current" | tail -n +3 | head -n 300 || true
printf '```\n\n'
else
printf 'There is no record yet.\n\n'
fi
} >> "$GITHUB_STEP_SUMMARY"
echo "::error title=Public API record::The public API differs from $record. Commit the file from this run's public-api-record artifact and add a changelog line."
done
exit "$status"
46 changes: 46 additions & 0 deletions .github/scripts/public_api_report.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
#!/usr/bin/env bash
# Writes the report of a pull request's public API changes to the job summary, and to the step output "report", which
# the workflow's comment job posts on the pull request. The comment lists at most 200 lines per section.
# $1 a file with one removed or changed declaration per line
# $2 a file with one declaration per line that the pull request adds to the public API
set -euo pipefail
breaking=$1
added=$2
marker='<!-- countly-public-api -->'

# Prints a section titled $1 and explained by $2 with the lines of file $3, at most $4 of them when $4 is not 0.
section() {
local count
count=$(grep -c . "$3" || true)
[ "$count" -gt 0 ] || return 0
printf '**%s: %s.** %s\n\n```\n' "$1" "$count" "$2"
if [ "$4" -gt 0 ]; then
head -n "$4" "$3"
else
cat "$3"
fi
printf '```\n'
if [ "$4" -gt 0 ] && [ "$count" -gt "$4" ]; then
printf '\n%s more in the job summary.\n' "$((count - $4))"
fi
printf '\n'
}

# Prints the whole report, with at most $1 lines per section when $1 is not 0.
report() {
printf '%s\n### Public API changes\n\n' "$marker"
if ! grep -q . "$breaking" && ! grep -q . "$added"; then
printf 'No public API change.\n'
return
fi
section 'Removed or changed' 'Each needs a CHANGELOG entry that marks it as a breaking change.' "$breaking" "$1"
section 'Added' 'Check that each one is meant to be public.' "$added" "$1"
}

report 0 >> "$GITHUB_STEP_SUMMARY"
delimiter="EOF_$(od -An -N8 -tx1 /dev/urandom | tr -d ' \n')"
{
echo "report<<$delimiter"
report 200
echo "$delimiter"
} >> "$GITHUB_OUTPUT"
53 changes: 53 additions & 0 deletions .github/workflows/api-changelog.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
name: Public API changelog

# A pull request that changes or removes a record of the public API, or of the requests the SDK sends, must also change
# the CHANGELOG.md that API_FILES pairs it with, so that the release notes tell integrators about every such change. A
# record the pull request adds needs no line. A path ending in "/" stands for every file under it. The API and request
# checks keep each record in step with the SDK.
on:
pull_request:
branches: [master, staging]

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

permissions:
pull-requests: read # to list the files the pull request changes

jobs:
changelog:
name: A public API or request change comes with a CHANGELOG line
runs-on: ubuntu-24.04
steps:
- name: Check the files the pull request changes
env:
GH_TOKEN: ${{ github.token }}
REPO: ${{ github.repository }}
PR: ${{ github.event.pull_request.number }}
API_FILES: api/countly-sdk-nodejs.api=CHANGELOG.md api/requests/=CHANGELOG.md
run: |
changed=$(gh api "repos/$REPO/pulls/$PR/files" --paginate --jq '.[] | select(.status != "added") | .filename')
changes() {
case "$1" in
*/) printf '%s\n' "$changed" | awk -v prefix="$1" 'index($0, prefix) == 1 { found = 1 } END { exit !found }' ;;
*) printf '%s\n' "$changed" | grep -qxF "$1" ;;
esac
}
recorded_changed=no
for pair in $API_FILES; do
record=${pair%%=*}
changelog=${pair#*=}
if changes "$record"; then
recorded_changed=yes
if ! changes "$changelog"; then
echo "::error::This pull request changes $record, which records the public API or the requests the SDK sends, but not $changelog. Add a line that tells integrators what changed."
exit 1
fi
fi
done
if [ "$recorded_changed" = yes ]; then
echo "The recorded public API or requests change, and the CHANGELOG changes with them."
else
echo "This pull request changes neither the recorded public API nor the recorded requests."
fi
101 changes: 101 additions & 0 deletions .github/workflows/public_api.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
name: Public API changes

on:
pull_request:

permissions:
contents: read

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
api:
name: Breaking changes
outputs:
report: ${{ steps.report.outputs.report }}
runs-on: ubuntu-24.04
steps:
- name: Checkout SDK code
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 2
persist-credentials: false

- name: Set up Node.js
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24

# The first parent of the pull request's merge commit is the base branch it merges into.
- name: Compare the public API with the base branch
id: compare
run: |
git worktree add "$RUNNER_TEMP/base" HEAD^1
roots=(
'Countly=sdk'
'Bulk=new sdk.Bulk({ app_key: "key", url: "https://example.invalid", persist_queue: false })'
'BulkUser=new sdk.Bulk({ app_key: "key", url: "https://example.invalid", persist_queue: false }).add_user({ device_id: "id" })'
)
node .github/scripts/public_api.mjs "$RUNNER_TEMP/base/lib/countly.js" "${roots[@]}" > "$RUNNER_TEMP/base.txt"
node .github/scripts/public_api.mjs lib/countly.js "${roots[@]}" > "$RUNNER_TEMP/head.txt"
LC_ALL=C comm -23 "$RUNNER_TEMP/base.txt" "$RUNNER_TEMP/head.txt" | sed 's/^/Removed or changed: /' > "$RUNNER_TEMP/breaking.txt"
LC_ALL=C comm -13 "$RUNNER_TEMP/base.txt" "$RUNNER_TEMP/head.txt" > "$RUNNER_TEMP/added.txt"

- name: Report the public API changes
id: report
run: bash .github/scripts/public_api_report.sh "$RUNNER_TEMP/breaking.txt" "$RUNNER_TEMP/added.txt"

- name: Require a CHANGELOG entry for breaking changes
run: |
if [ ! -s "$RUNNER_TEMP/breaking.txt" ]; then
exit 0
fi
if git diff --quiet HEAD^1 HEAD -- CHANGELOG.md; then
echo "::error title=Breaking API change::This pull request breaks the public API without a CHANGELOG.md entry. The job summary lists each break."
exit 1
fi
echo "::warning title=Breaking API change::This pull request breaks the public API. Check that CHANGELOG.md marks it as a breaking change."

# The committed record keeps every change to the public API visible in the pull request's diff.
- name: Compare the public API with its record
id: record
if: ${{ !cancelled() && steps.compare.outcome == 'success' }}
run: >
bash .github/scripts/public_api_record.sh
"$RUNNER_TEMP/head.txt=api/countly-sdk-nodejs.api"

- name: Upload the new record
if: ${{ !cancelled() && steps.record.outcome == 'failure' }}
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: public-api-record
path: ${{ runner.temp }}/public-api-record

comment:
name: Comment the public API changes
needs: api
# A fork's or Dependabot's pull request only gets a read-only token, so its report stays in the job summary.
if: >-
always() && needs.api.outputs.report != '' &&
github.event.pull_request.head.repo.full_name == github.repository &&
github.event.pull_request.user.login != 'dependabot[bot]'
runs-on: ubuntu-24.04
permissions:
pull-requests: write
steps:
- name: Post or update the comment
env:
GH_TOKEN: ${{ github.token }}
REPO: ${{ github.repository }}
PR: ${{ github.event.pull_request.number }}
REPORT: ${{ needs.api.outputs.report }}
run: |
id=$(gh api --paginate "repos/$REPO/issues/$PR/comments" --jq \
'.[] | select(.user.login == "github-actions[bot]" and (.body | startswith("<!-- countly-public-api -->"))) | .id' | tail -n 1)
if [ -n "$id" ]; then
gh api --method PATCH "repos/$REPO/issues/comments/$id" -f "body=$REPORT" > /dev/null
elif ! grep -qx 'No public API change.' <<< "$REPORT"; then
gh api --method POST "repos/$REPO/issues/$PR/comments" -f "body=$REPORT" > /dev/null
fi
Loading
Loading