Skip to content

Commit 54462a9

Browse files
JohnRDOrazioJohnRDOrazio
authored
Merge pull request #9 from CatholicOS/feature/unified-project-governance
Unify Project Governance and AI Governance into single framework
2 parents 3e6f226 + 247fea8 commit 54462a9

14 files changed

Lines changed: 1503 additions & 1117 deletions

‎.github/workflows/deploy-docs.yml‎

Lines changed: 98 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,9 @@ jobs:
2525
run: |
2626
# All governed documents: directory/filename (without .md)
2727
DOCS=(
28-
"ai-governance/ai-vetting-criteria"
29-
"ai-governance/fragmented-catholic-ai-governance"
30-
"ai-governance/governance-as-code-catholic-ai"
31-
"ai-governance/trusted-synthetic-data-ministry-ai"
28+
"research/fragmented-catholic-digital-governance"
29+
"research/governance-as-code-catholic-technology"
30+
"research/trusted-data-infrastructure-catholic-ministry"
3231
"project-governance/definitions"
3332
"project-governance/project-types"
3433
"project-governance/lifecycle"
@@ -73,6 +72,24 @@ jobs:
7372
7473
echo "changed_docs=$CHANGED_DOCS" >> "$GITHUB_OUTPUT"
7574
75+
# Detect deleted governance documents (stale pages to remove)
76+
DELETED_DOCS=""
77+
if [ "$DEPLOY_ALL" != true ] && [ -n "$DIFF_BASE" ]; then
78+
DELETED=$(git diff --name-only --diff-filter=D "$DIFF_BASE" HEAD 2>/dev/null || echo "")
79+
for FILE in $DELETED; do
80+
case "$FILE" in
81+
# Skip non-governance markdown files
82+
README.md|RELEASING.md|CONTRIBUTING.md|CHANGELOG.md|*/README.md) continue ;;
83+
*/*.md)
84+
DOC="${FILE%.md}"
85+
echo " Deleted: $FILE"
86+
DELETED_DOCS="${DELETED_DOCS:+$DELETED_DOCS }${DOC}"
87+
;;
88+
esac
89+
done
90+
fi
91+
echo "deleted_docs=$DELETED_DOCS" >> "$GITHUB_OUTPUT"
92+
7693
- name: Install pandoc
7794
uses: pandoc/actions/setup@ae312111f8aecde13e11672badd8c90a26b036c0 # v1.1.1
7895

@@ -86,23 +103,22 @@ jobs:
86103
run: |
87104
# Document titles keyed by directory/basename
88105
declare -A DOC_TITLES=(
89-
["ai-governance/ai-vetting-criteria"]="CDCF Project Vetting Criteria: AI Tools"
90-
["ai-governance/fragmented-catholic-ai-governance"]="Fragmented Catholic AI Governance at Scale"
91-
["ai-governance/governance-as-code-catholic-ai"]="Governance-as-Code for Catholic AI Agent Deployment"
92-
["ai-governance/trusted-synthetic-data-ministry-ai"]="Trusted Synthetic Data for Ministry-Scale AI"
106+
["research/fragmented-catholic-digital-governance"]="Fragmented Catholic Digital Governance at Scale"
107+
["research/governance-as-code-catholic-technology"]="Governance-as-Code for Catholic Technology Deployment"
108+
["research/trusted-data-infrastructure-catholic-ministry"]="Trusted Data Infrastructure for Catholic Ministry"
93109
["project-governance/definitions"]="CDCF Governance Definitions"
94110
["project-governance/project-types"]="CDCF Project Types: Foundation Projects and Community Projects"
95111
["project-governance/lifecycle"]="CDCF Project Lifecycle"
96-
["project-governance/project-vetting-criteria"]="CDCF Project Vetting Criteria: General Framework"
112+
["project-governance/project-vetting-criteria"]="CDCF Project Vetting Criteria"
97113
["project-governance/committees"]="CDCF Governance Bodies"
98114
["standards/overview"]="CDCF Standards: Overview"
99115
["standards/committees"]="CDCF Standards Committees"
100116
)
101117
102118
# Parent page slugs for each section
103119
declare -A SECTION_PARENTS=(
104-
["ai-governance"]="ai-governance"
105120
["project-governance"]="project-governance"
121+
["research"]="research"
106122
["standards"]="standards"
107123
)
108124
@@ -228,6 +244,78 @@ jobs:
228244
echo ""
229245
echo "All translations complete."
230246
247+
- name: Remove stale WordPress pages
248+
if: steps.changes.outputs.deleted_docs != ''
249+
env:
250+
WP_REST_URL: ${{ vars.WP_REST_URL }}
251+
WP_APP_USERNAME: ${{ secrets.WP_APP_USERNAME }}
252+
WP_APP_PASSWORD: ${{ secrets.WP_APP_PASSWORD }}
253+
run: |
254+
STALE_SECTIONS=()
255+
256+
for DOC in ${{ steps.changes.outputs.deleted_docs }}; do
257+
SECTION=$(dirname "$DOC")
258+
BASENAME=$(basename "$DOC")
259+
if [ "$SECTION" = "standards" ]; then
260+
SLUG="standards-${BASENAME}"
261+
else
262+
SLUG="$BASENAME"
263+
fi
264+
265+
echo "Checking for stale page: ${SLUG}..."
266+
EXISTING=$(curl -s \
267+
-u "$WP_APP_USERNAME:$WP_APP_PASSWORD" \
268+
"$WP_REST_URL/wp/v2/pages?slug=${SLUG}&status=publish,draft")
269+
270+
PAGE_ID=$(echo "$EXISTING" | jq -r 'if type == "array" then .[0].id // empty else empty end')
271+
272+
if [ -n "$PAGE_ID" ] && [ "$PAGE_ID" != "null" ]; then
273+
echo " Trashing page ID $PAGE_ID (slug: ${SLUG})..."
274+
HTTP_CODE=$(curl -s -o /dev/null -w '%{http_code}' -X DELETE \
275+
-u "$WP_APP_USERNAME:$WP_APP_PASSWORD" \
276+
"$WP_REST_URL/wp/v2/pages/$PAGE_ID")
277+
if [[ "$HTTP_CODE" -lt 300 ]]; then
278+
echo " Trashed."
279+
else
280+
echo " Warning: delete returned HTTP $HTTP_CODE"
281+
fi
282+
else
283+
echo " No WordPress page found — skipping."
284+
fi
285+
286+
# Track sections that had deletions
287+
if [[ ! " ${STALE_SECTIONS[*]} " =~ " ${SECTION} " ]]; then
288+
STALE_SECTIONS+=("$SECTION")
289+
fi
290+
done
291+
292+
# If an entire section directory no longer exists, trash the parent page
293+
for SECTION in "${STALE_SECTIONS[@]}"; do
294+
if [ ! -d "$SECTION" ]; then
295+
echo "Section '${SECTION}' no longer exists — checking for stale parent page..."
296+
PARENT=$(curl -s \
297+
-u "$WP_APP_USERNAME:$WP_APP_PASSWORD" \
298+
"$WP_REST_URL/wp/v2/pages?slug=${SECTION}&status=publish,draft")
299+
300+
PARENT_ID=$(echo "$PARENT" | jq -r 'if type == "array" then .[0].id // empty else empty end')
301+
302+
if [ -n "$PARENT_ID" ] && [ "$PARENT_ID" != "null" ]; then
303+
echo " Trashing parent page ID $PARENT_ID (slug: ${SECTION})..."
304+
HTTP_CODE=$(curl -s -o /dev/null -w '%{http_code}' -X DELETE \
305+
-u "$WP_APP_USERNAME:$WP_APP_PASSWORD" \
306+
"$WP_REST_URL/wp/v2/pages/$PARENT_ID")
307+
if [[ "$HTTP_CODE" -lt 300 ]]; then
308+
echo " Trashed."
309+
else
310+
echo " Warning: delete returned HTTP $HTTP_CODE"
311+
fi
312+
fi
313+
fi
314+
done
315+
316+
echo ""
317+
echo "Stale page cleanup complete."
318+
231319
- name: Setup Node.js
232320
uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
233321
with:

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
node_modules/
2+
dist/

‎README.md‎

Lines changed: 17 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -24,39 +24,36 @@ A working repository for governance documentation supporting the **Catholic Digi
2424
This repository holds the policy frameworks, evaluation criteria, and research documentation that inform how the CDCF reviews, incubates, and graduates technology projects. It is
2525
modeled on established foundation governance (such as the Apache Software Foundation) but is uniquely grounded in Catholic Social Teaching and Canon Law.
2626

27-
The documentation is organized into a general project governance framework, applicable to all technology projects, and specialized domain-specific criteria (starting with AI
28-
governance).
27+
The documentation is organized into a unified project governance framework (with domain-specific extensions for AI integrated inline), supplementary research memos, and standards
28+
for canonical data interoperability.
2929

3030
---
3131

3232
## Document Stack
3333

34-
### General Project Governance
34+
### Project Governance
3535

3636
The core frameworks for any project seeking CDCF endorsement.
3737

38-
| Document | Type | Description |
39-
| :------------------------------------------------------------------------------ | :--------- | :------------------------------------------------------------------------------------- |
40-
| [project-vetting-criteria.md](./project-governance/project-vetting-criteria.md) | **Policy** | The foundational 8 criteria for any CDCF project. |
41-
| [lifecycle.md](./project-governance/lifecycle.md) | Procedure | Definition of the stages from proposal through incubation, graduation, and retirement. |
42-
| [committees.md](./project-governance/committees.md) | Structure | Governance bodies: Board of Directors, TCSC, and PMCs. |
43-
| [project-types.md](./project-governance/project-types.md) | Policy | Distinction between Foundation Projects and Community Projects. |
44-
| [definitions.md](./project-governance/definitions.md) | Glossary | Shared vocabulary for CDCF governance and vetting. |
38+
| Document | Type | Description |
39+
| :------------------------------------------------------------------------------ | :--------- | :-------------------------------------------------------------------------------------------------------- |
40+
| [project-vetting-criteria.md](./project-governance/project-vetting-criteria.md) | **Policy** | The foundational 8 criteria for any CDCF project, with AI domain extensions integrated inline. |
41+
| [lifecycle.md](./project-governance/lifecycle.md) | Procedure | Definition of the stages from proposal through incubation, graduation, and retirement. |
42+
| [committees.md](./project-governance/committees.md) | Structure | Governance bodies: Board of Directors, TCSC, and PMCs. |
43+
| [project-types.md](./project-governance/project-types.md) | Policy | Distinction between Foundation Projects and Community Projects. |
44+
| [definitions.md](./project-governance/definitions.md) | Glossary | Shared vocabulary for CDCF governance and vetting. |
4545

4646
---
4747

48-
### Specialized Domain Governance
48+
### Research
4949

50-
Domain-specific extensions to the general framework.
50+
Supplementary research memos informing the design of the vetting criteria.
5151

52-
#### AI Governance
53-
54-
| Document | Type | Description |
55-
| :--------------------------------------------------------------------------------------------- | :------------ | :-------------------------------------------------------------------------- |
56-
| [ai-vetting-criteria.md](./ai-governance/ai-vetting-criteria.md) | **Policy** | Operational vetting criteria for AI tools, extending the general framework. |
57-
| [fragmented-catholic-ai-governance.md](./ai-governance/fragmented-catholic-ai-governance.md) | Research memo | The urgency of shared AI governance standards. |
58-
| [governance-as-code-catholic-ai.md](./ai-governance/governance-as-code-catholic-ai.md) | Research memo | Machine-enforceable deployment governance architecture. |
59-
| [trusted-synthetic-data-ministry-ai.md](./ai-governance/trusted-synthetic-data-ministry-ai.md) | Research memo | Synthetic data infrastructure for ministry-scale AI. |
52+
| Document | Type | Description |
53+
| :------------------------------------------------------------------------------------------ | :------------ | :------------------------------------------------------ |
54+
| [fragmented-catholic-digital-governance.md](./research/fragmented-catholic-digital-governance.md) | Research memo | The urgency of shared digital governance standards. |
55+
| [governance-as-code-catholic-technology.md](./research/governance-as-code-catholic-technology.md) | Research memo | Machine-enforceable deployment governance architecture. |
56+
| [trusted-data-infrastructure-catholic-ministry.md](./research/trusted-data-infrastructure-catholic-ministry.md) | Research memo | Trusted data infrastructure for Catholic ministry. |
6057

6158
---
6259

‎RELEASING.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Releasing
2+
3+
This document describes how governance documents are built, deployed, and released.
4+
5+
## Overview
6+
7+
The release pipeline is driven by the GitHub Actions workflow
8+
`.github/workflows/deploy-docs.yml`. It triggers on:
9+
10+
- **Tag push** matching `v*` (e.g. `v0.2`) -- deploys only documents changed
11+
since the previous tag.
12+
- **Manual dispatch** (`workflow_dispatch`) -- deploys all documents.
13+
14+
A single workflow run performs four stages in order:
15+
16+
1. Deploy changed documents to WordPress
17+
2. Translate deployed pages
18+
3. Build standalone HTML and combined PDF artifacts
19+
4. Create (or update) a GitHub release with those artifacts
20+
21+
## Prerequisites
22+
23+
The following repository secrets and variables must be configured in GitHub:
24+
25+
| Name | Type | Purpose |
26+
| :------------------ | :------- | :----------------------------------------------- |
27+
| `WP_REST_URL` | Variable | Base URL of the WordPress REST API |
28+
| `WP_APP_USERNAME` | Secret | WordPress application password username |
29+
| `WP_APP_PASSWORD` | Secret | WordPress application password |
30+
31+
The WordPress site must also expose a custom REST endpoint
32+
(`cdcf/v1/translate`) that accepts a `source_id` and `target_lang` for the
33+
translation step.
34+
35+
## How to release
36+
37+
### 1. Prepare the branch
38+
39+
Ensure all changes are merged to `main` and that quality checks pass:
40+
41+
```bash
42+
npm run lint:md # 0 errors expected
43+
npm run build:html # standalone HTML files in dist/
44+
npm run build:pdf # combined PDF in dist/
45+
```
46+
47+
### 2. Tag and push
48+
49+
```bash
50+
git tag v0.X
51+
git push origin v0.X
52+
```
53+
54+
This triggers the deploy workflow automatically.
55+
56+
Alternatively, run the workflow manually from the GitHub Actions tab
57+
(**Run workflow** on the `main` branch). Manual runs deploy all documents and
58+
auto-increment the version tag.
59+
60+
### 3. What the workflow does
61+
62+
#### Stage 1 -- WordPress deployment
63+
64+
- Compares the tagged commit against the previous tag to determine which
65+
`.md` files changed.
66+
- Converts each changed document from Markdown to HTML using `pandoc` with
67+
the Lua filter `scripts/fix-internal-links.lua` (which rewrites internal
68+
`.md` links for the target output format).
69+
- Creates or updates the corresponding WordPress page via the REST API,
70+
organized under parent pages (`project-governance`, `research`, `standards`).
71+
72+
#### Stage 1b -- Stale page cleanup
73+
74+
- Uses `git diff --diff-filter=D` between tags to detect governance `.md`
75+
files that were deleted or renamed since the previous release.
76+
- Derives the WordPress slug for each deleted file (using the same logic as
77+
deployment) and trashes the corresponding page.
78+
- If an entire section directory no longer exists (e.g. `ai-governance/` was
79+
removed), the parent page is also trashed.
80+
- Pages are moved to the WordPress trash (not permanently deleted), so they
81+
can be recovered if needed.
82+
- This step only runs for tag-triggered deploys (not manual dispatch, which
83+
has no previous tag to compare against).
84+
85+
#### Stage 2 -- Translation
86+
87+
- Each newly deployed page is translated into **it**, **es**, **fr**, **pt**,
88+
and **de** via the `cdcf/v1/translate` endpoint.
89+
90+
#### Stage 3 -- Build artifacts
91+
92+
- `npm run build:html` (`scripts/build-standalone-html.sh`) -- produces one
93+
self-contained HTML file per document in `dist/`, each with a navigation
94+
sidebar linking to the other documents.
95+
- `npm run build:pdf` (`scripts/build-combined-pdf.sh`) -- concatenates all
96+
documents into a single Markdown file, converts to standalone HTML, then
97+
renders a paginated PDF using `pagedjs-cli`.
98+
99+
Both scripts use `scripts/docs-print.css` for styling and
100+
`scripts/fix-internal-links.lua` for link rewriting.
101+
102+
#### Stage 4 -- GitHub release
103+
104+
- Creates a GitHub release titled **Governance Docs vX.Y** with all
105+
`dist/*.html` and `dist/*.pdf` files attached.
106+
- If the release already exists (e.g. re-run), assets are uploaded with
107+
`--clobber`.
108+
109+
## Local builds
110+
111+
You can build artifacts locally without deploying:
112+
113+
```bash
114+
npm install # first time only
115+
npm run build:html # dist/*.html
116+
npm run build:pdf # dist/cdcf-governance-docs.pdf (requires pagedjs-cli)
117+
```
118+
119+
The PDF build requires Google Chrome or Chromium installed locally
120+
(`pagedjs-cli` uses it for rendering). Set `PUPPETEER_EXECUTABLE_PATH` if
121+
the binary is not in the default location.
122+
123+
## Document inventory
124+
125+
The following documents are included in builds and deployments:
126+
127+
| Section | File |
128+
| :----------------- | :----------------------------------------------- |
129+
| Project Governance | `project-governance/project-vetting-criteria.md` |
130+
| Project Governance | `project-governance/lifecycle.md` |
131+
| Project Governance | `project-governance/committees.md` |
132+
| Project Governance | `project-governance/project-types.md` |
133+
| Project Governance | `project-governance/definitions.md` |
134+
| Research | `research/fragmented-catholic-digital-governance.md` |
135+
| Research | `research/governance-as-code-catholic-technology.md` |
136+
| Research | `research/trusted-data-infrastructure-catholic-ministry.md` |
137+
| Standards | `standards/overview.md` |
138+
| Standards | `standards/committees.md` |
139+
140+
To add a new document, update the `DOCS` array in all three places:
141+
142+
1. `.github/workflows/deploy-docs.yml` (lines 27-38 and 87-98)
143+
2. `scripts/build-standalone-html.sh` (lines 10-21)
144+
3. `scripts/build-combined-pdf.sh` (lines 12-24)

0 commit comments

Comments
 (0)