Skip to content

Commit ad80611

Browse files
marc0olomarc0olo
authored
infra: consolidate interface spec files, add team ownership and CI workflows (#220)
## Summary - **Content audit**: Verified all 7 `ic-interface-spec` split files are 1:1 with the portal source. All 4 attachment files are byte-for-byte identical. No content was lost; the only differences from the portal are expected frontmatter, cross-file link rewrites, and one intentional adaptation (dead `internetcomputer.org/docs/` links replaced with live local paths). - **Inline Candid interface**: Restored the portal's inline `ic.did` embed in the management canister spec (`docs/references/ic-interface-spec/management-canister.md`). A new `plugins/remark-include-file.mjs` remark plugin handles `file=<rootDir>/...` code fence attributes at build time, using the project's own `unist-util-visit@5` (avoids the version conflict from `remark-code-import`). - **File consolidation**: Moved all interface spec attachments into a single flat `public/references/` directory: - `public/reference/ic.did` → `public/references/ic.did` - `public/references/_attachments/certificates.cddl` → `public/references/certificates.cddl` - `public/references/_attachments/requests.cddl` → `public/references/requests.cddl` - `public/references/_attachments/http-gateway.did` → `public/references/http-gateway.did` - **File rename**: `docs/references/http-gateway-spec.md` → `docs/references/http-gateway-protocol-spec.md` (matches portal filename; all internal links and sidebar updated). - **CODEOWNERS**: Added required reviewers for spec files and attachments: - `docs/references/ic-interface-spec/*` — `@dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx` - `docs/references/http-gateway-protocol-spec.md` — same - `docs/references/management-canister.md` — same - `docs/references/execution-errors.md` — `@dfinity/team-dsm @dfinity/dx` - All four files in `public/references/` individually — same as interface-spec - **CI workflows** (ported and adapted from `dfinity/portal`): - `interface-spec.yml` — validates `.cddl` files (docker cddl-cli) and `.did` files (didc) on every PR touching spec files, and on push to `main` - `interface-spec-tag.yml` — labels any PR that touches spec files with `interface-spec`; creates the label automatically on first run (idempotent) - `interface-spec-slack.yml` — posts to `#interface-spec` on Slack when a non-draft PR is opened or marked ready for review (requires `SLACK_API_TOKEN` secret) ## Notes - `SLACK_API_TOKEN` secret needs to be added to the repo for the Slack workflow to function. - One numeric claim in `docs/references/execution-errors.md` needs DSM/Consensus confirmation: "wasm64 modules can use up to 6 GiB of heap memory." This appears in `portal/canisters.mdx` and our `cycles-costs.md` but not in `portal/resource-limits.mdx`. Please verify against the runtime implementation before merging. ## Sync recommendation `informed by dfinity/portal — .github/workflows/interface-spec.yml, .github/workflows/interface-spec-tag.yml, .github/workflows/interface-spec-slack.yml`
1 parent 51834c6 commit ad80611

19 files changed

Lines changed: 193 additions & 16 deletions

‎.github/CODEOWNERS‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# All files are owned by the DX team.
22
# At least one DX team member must approve every PR before it can be merged.
3-
# DX team members are also configured as bypass actors in the branch ruleset
4-
# and can merge their own PRs without a separate review.
53
* @dfinity/dx
4+
5+
# Interface specification — additional required reviewers for spec files and attachments.
6+
# GitHub CODEOWNERS: last matching rule wins, so these override the wildcard above.
7+
docs/references/ic-interface-spec/* @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
8+
docs/references/http-gateway-protocol-spec.md @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
9+
docs/references/management-canister.md @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
10+
docs/references/execution-errors.md @dfinity/team-dsm @dfinity/dx
11+
public/references/ic.did @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
12+
public/references/certificates.cddl @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
13+
public/references/requests.cddl @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
14+
public/references/http-gateway.did @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx

‎.github/workflows/interface-spec-slack.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: Interface Specification PR Slack Notification
2+
3+
on:
4+
pull_request:
5+
types: [opened, ready_for_review]
6+
paths:
7+
- .github/workflows/interface-spec.yml
8+
- .github/workflows/interface-spec-tag.yml
9+
- .github/workflows/interface-spec-slack.yml
10+
- docs/references/ic-interface-spec/**
11+
- docs/references/http-gateway-protocol-spec.md
12+
- public/references/certificates.cddl
13+
- public/references/requests.cddl
14+
- public/references/http-gateway.did
15+
- public/references/ic.did
16+
17+
jobs:
18+
notify-slack:
19+
name: Notify Slack
20+
if: github.event.pull_request.draft == false
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
24+
25+
- name: Sanitize PR title
26+
id: sanitize
27+
env:
28+
RAW_TITLE: ${{ github.event.pull_request.title }}
29+
run: |
30+
ESCAPED_TITLE=$(echo "$RAW_TITLE" \
31+
| sed 's/&/\&amp;/g' \
32+
| sed 's/</\&lt;/g' \
33+
| sed 's/>/\&gt;/g')
34+
echo "safe_title=$ESCAPED_TITLE" >> "$GITHUB_OUTPUT"
35+
36+
- name: Post to Slack
37+
uses: slackapi/slack-github-action@91efab103c0de0a537f72a35f6b8cda0ee76bf0a # v2.1.1
38+
with:
39+
method: chat.postMessage
40+
token: ${{ secrets.SLACK_API_TOKEN }}
41+
payload: |
42+
channel: interface-spec
43+
text: ":github: `${{ github.repository }}` <${{ github.event.pull_request.html_url }}|${{ steps.sanitize.outputs.safe_title }}>"

‎.github/workflows/interface-spec-tag.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Interface Specification Tag
2+
3+
on:
4+
pull_request_target:
5+
paths:
6+
- .github/workflows/interface-spec.yml
7+
- .github/workflows/interface-spec-tag.yml
8+
- .github/workflows/interface-spec-slack.yml
9+
- docs/references/ic-interface-spec/**
10+
- docs/references/http-gateway-protocol-spec.md
11+
- public/references/certificates.cddl
12+
- public/references/requests.cddl
13+
- public/references/http-gateway.did
14+
- public/references/ic.did
15+
16+
jobs:
17+
interface-spec-tag:
18+
name: Tag PR with interface-spec
19+
runs-on: ubuntu-latest
20+
permissions:
21+
issues: write
22+
pull-requests: write
23+
steps:
24+
- name: Create label if missing
25+
run: |
26+
gh label create interface-spec \
27+
--color 0075ca \
28+
--description "Changes to the IC interface specification" \
29+
--repo ${{ github.repository }} \
30+
--force
31+
env:
32+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
33+
34+
- name: Tag PR with interface-spec
35+
run: |
36+
gh pr edit ${{ github.event.pull_request.number }} \
37+
--add-label interface-spec \
38+
--repo ${{ github.repository }}
39+
env:
40+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/interface-spec.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Interface Specification
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- .github/workflows/interface-spec.yml
7+
- docs/references/ic-interface-spec/**
8+
- docs/references/http-gateway-protocol-spec.md
9+
- public/references/certificates.cddl
10+
- public/references/requests.cddl
11+
- public/references/http-gateway.did
12+
- public/references/ic.did
13+
push:
14+
branches:
15+
- main
16+
17+
jobs:
18+
cddl:
19+
name: Check cddl files
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
23+
- name: Check cddl files
24+
run: |
25+
docker run --rm -v $PWD/public/references:/workdir ghcr.io/anweiss/cddl-cli:0.9.1 compile-cddl --cddl /workdir/certificates.cddl
26+
docker run --rm -v $PWD/public/references:/workdir ghcr.io/anweiss/cddl-cli:0.9.1 compile-cddl --cddl /workdir/requests.cddl
27+
28+
candid:
29+
name: Check candid files
30+
runs-on: ubuntu-latest
31+
steps:
32+
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
33+
- name: Check candid files
34+
run: |
35+
curl -L https://github.com/dfinity/candid/releases/download/2023-07-25/didc-linux64 -o didc
36+
chmod +x didc
37+
./didc check public/references/http-gateway.did
38+
./didc check public/references/ic.did

‎astro.config.mjs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import remarkIcpCliVersion from "./plugins/remark-icp-cli-version.mjs";
77
import remarkSnippet from "./plugins/remark-snippet.mjs";
88
import remarkHeadingId from "./plugins/remark-heading-id.mjs";
99
import remarkPlantUML from "./plugins/remark-plantuml.mjs";
10+
import remarkIncludeFile from "./plugins/remark-include-file.mjs";
1011
import agentDocs from "./plugins/astro-agent-docs.mjs";
1112
import { sidebar } from "./sidebar.mjs";
1213
import { TITLE, DESCRIPTION, PUBLISHER, OG_ALT } from "./src/branding.mjs";
@@ -18,7 +19,7 @@ export default defineConfig({
1819
// Rehype plugins work with Starlight (remark plugins don't — Starlight overrides them).
1920
// See: https://github.com/dfinity/icp-cli/issues/423
2021
rehypePlugins: [rehypeRewriteLinks, rehypeExternalLinks],
21-
remarkPlugins: [remarkHeadingId, remarkSnippet, remarkIcpCliVersion, remarkPlantUML],
22+
remarkPlugins: [remarkHeadingId, remarkSnippet, remarkIcpCliVersion, remarkPlantUML, remarkIncludeFile],
2223
},
2324
integrations: [
2425
starlight({

‎docs/guides/frontends/certification.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -318,6 +318,6 @@ For the full working example including a backend canister, see the [certified-co
318318
- [Asset canister](asset-canister.md): deploy and configure the standard asset canister with automatic certification
319319
- [Certified variables](../backends/certified-variables.md): certify Candid query responses from backend canisters
320320
- [Security concepts](../../concepts/security.md): why query integrity matters
321-
- [HTTP Gateway specification](../../references/http-gateway-spec.md): how boundary nodes verify responses
321+
- [HTTP Gateway specification](../../references/http-gateway-protocol-spec.md): how boundary nodes verify responses
322322

323323
<!-- Upstream: informed by dfinity/response-verification — packages/ic-asset-certification/README.md, packages/ic-http-certification/README.md, packages/certificate-verification-js/README.md, packages/certificate-verification-js/src/index.ts, examples/certification/certified-counter; dfinity/portal — docs/building-apps/frontends/asset-security.mdx; dfinity/icskills — skills/certified-variables/SKILL.md, skills/asset-canister/SKILL.md -->

docs/references/http-gateway-spec.md renamed to docs/references/http-gateway-protocol-spec.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -434,7 +434,7 @@ service : {
434434
}
435435
```
436436

437-
You can also [download the file](/references/_attachments/http-gateway.did).
437+
You can also [download the file](/references/http-gateway.did).
438438

439439
Not all of this interface is required. The following sections detail what can be optionally omitted depending on the requirements of the canister in question.
440440

‎docs/references/ic-interface-spec/certification.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,7 @@ Delegations are *scoped*, i.e., they indicate which set of canister principals t
179179

180180
### Encoding of certificates {#certification-encoding}
181181

182-
The binary encoding of a certificate is a CBOR (see [CBOR](./index.md#cbor)) value according to the following CDDL (see [CDDL](./index.md#cddl)). You can also [download the file](/references/_attachments/certificates.cddl).
182+
The binary encoding of a certificate is a CBOR (see [CBOR](./index.md#cbor)) value according to the following CDDL (see [CDDL](./index.md#cddl)). You can also [download the file](/references/certificates.cddl).
183183

184184
The values in the [The system state tree](./index.md#state-tree) are encoded to blobs as follows:
185185

@@ -251,6 +251,6 @@ In the pruned tree, the `lookup_path` function behaves as follows:
251251

252252
## The HTTP Gateway protocol {#http-gateway}
253253

254-
The HTTP Gateway Protocol has been moved into its own [specification](../http-gateway-spec.md).
254+
The HTTP Gateway Protocol has been moved into its own [specification](../http-gateway-protocol-spec.md).
255255

256256
<!-- Upstream: sync from dfinity/portal — docs/references/ic-interface-spec.md -->

‎docs/references/ic-interface-spec/https-interface.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -735,7 +735,7 @@ A typical request would be (written in [CBOR diagnostic notation](https://www.rf
735735

736736
### CDDL description of requests and responses {#api-cddl}
737737

738-
This section summarizes the format of the CBOR data passed to and from the entry points described above. You can also [download the file](/references/_attachments/requests.cddl) and see [CDDL](./index.md#cddl) for more information.
738+
This section summarizes the format of the CBOR data passed to and from the entry points described above. You can also [download the file](/references/requests.cddl) and see [CDDL](./index.md#cddl) for more information.
739739

740740
### Ordering guarantees
741741

‎docs/references/ic-interface-spec/management-canister.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,10 @@ It is possible to use the management canister via external requests (a.k.a. ingr
2222

2323
### Interface overview {#ic-candid}
2424

25-
The [interface description](/reference/ic.did), in [Candid syntax](../candid-spec.md), describes the available functionality.
25+
The interface description below, in [Candid syntax](../candid-spec.md), describes the available functionality. You can also [download the file](/references/ic.did).
26+
27+
```candid file=<rootDir>/public/references/ic.did
28+
```
2629

2730
The binary encoding of arguments and results are as per Candid specification.
2831

0 commit comments

Comments
 (0)