Skip to content
Draft
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
71 changes: 71 additions & 0 deletions .github/workflows/dtc-pipeline.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Copyright 2026 UCP Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

name: DTC Review Pipeline

on:
schedule:
# Sync Next DTC Agenda assignees and General Track field every 15 minutes
- cron: "*/15 * * * *"
# Refresh Community Spotlight scores and pool daily at 06:00 UTC
- cron: "0 6 * * *"
repository_dispatch:
types:
- projects_v2_item
workflow_dispatch:
inputs:
mode:
description: "Command to execute (sync-agenda-assignees or scan-spotlight)"
required: false
type: choice
options:
- sync-agenda-assignees
- scan-spotlight
default: "sync-agenda-assignees"

permissions:
contents: read # Check out org-tools/dtc-pipeline scripts

jobs:
dtc-pipeline:
name: Run DTC Pipeline
runs-on: ubuntu-latest
permissions:
contents: read # Check out org-tools/dtc-pipeline scripts
steps:
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Set up uv
uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
with:
python-version: "3.12"
enable-cache: "false"

- name: Sync Next DTC Agenda assignees and General Track
if: inputs.mode != 'scan-spotlight' && github.event.schedule != '0 6 * * *'
env:
ORG_TRIAGE_TOKEN: ${{ secrets.ORG_TRIAGE_TOKEN }}
DTC_PROJECT_ID: ${{ vars.DTC_PROJECT_ID }}
run: uv run --frozen python org-tools/dtc-pipeline/scripts/dtc_pipeline.py sync-agenda-assignees --apply

- name: Run Community Spotlight scan
if: inputs.mode == 'scan-spotlight' || github.event.schedule == '0 6 * * *'
env:
ORG_TRIAGE_TOKEN: ${{ secrets.ORG_TRIAGE_TOKEN }}
DTC_PROJECT_ID: ${{ vars.DTC_PROJECT_ID }}
ORG_NAME: ${{ github.repository_owner }}
run: uv run --frozen python org-tools/dtc-pipeline/scripts/dtc_pipeline.py scan-spotlight --org "$ORG_NAME" --repo ucp --apply
3 changes: 3 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -54,3 +54,6 @@ jobs:
uv run --with jsonschema==4.26.0 --with markdown-it-py==3.0.0
--with markdown==3.10.2
python -m unittest discover -s org-tools/requirements-extractor/tests

- name: Run dtc-pipeline tests
run: uv run --frozen python -m unittest discover -s org-tools/dtc-pipeline/tests
5 changes: 4 additions & 1 deletion org-tools/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ This directory contains CLI utilities and configuration files for organization-w

```text
org-tools/
├── dtc-pipeline/ # DTC review pipeline & Community Spotlight engine (see dtc-pipeline/README.md)
├── governance/ # PR governance gate and approval verification (see governance/README.md)
├── label-sync/ # GitHub label synchronization utility (see label-sync/README.md)
├── requirements-extractor/ # Requirements catalog from specification prose (see requirements-extractor/README.md)
Expand All @@ -22,6 +23,7 @@ org-tools/
- **[🛡️ Automated Governance Gate](governance/README.md)**: Enforces path-based repository ownership rules and PR approval thresholds.
- **[📋 Requirements Extractor](requirements-extractor/README.md)**: Generates a machine-readable catalog of a specification's RFC 2119 requirements, and checks in CI that a committed catalog matches the specification.
- **[🤖 Central PR Triage Tool](triage/README.md)**: Automatically applies the `status:needs-triage` label to eligible open, non-draft Pull Requests.
- **[🗳️ DTC Review Pipeline & Community Spotlight Engine](dtc-pipeline/README.md)**: Provisions the unified 5-view `DTC Review Pipeline` Project v2 board, auto-assigns Technical Council members who move items into `Next DTC Agenda`, and runs the 3-gate + 100-point Community Spotlight scan.

---

Expand All @@ -36,5 +38,6 @@ uv run --with markdown-it-py==3.0.0 --with markdown==3.10.2 \
uv run python3 -m unittest discover -s org-tools/label-sync && \
uv run python3 -m unittest discover -s org-tools/triage/tests && \
uv run --with jsonschema==4.26.0 --with markdown-it-py==3.0.0 --with markdown==3.10.2 \
python3 -m unittest discover -s org-tools/requirements-extractor/tests
python3 -m unittest discover -s org-tools/requirements-extractor/tests && \
uv run python3 -m unittest discover -s org-tools/dtc-pipeline/tests
```
70 changes: 70 additions & 0 deletions org-tools/dtc-pipeline/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# DTC Review Pipeline & Community Spotlight Engine

Implements the governance workflow for surfacing and resolving Issues and Pull Requests in weekly Domain Technical Council meetings across `Universal-Commerce-Protocol/ucp`.

## Project Board Architecture (`DTC Review Pipeline`)

The pipeline manages a single public organization-level GitHub Project v2 board (**`DTC Review Pipeline`**) with 5 views, 6 `Status` columns, and 2 custom fields (`Track` and `Priority Score`).

### Views

| View | Layout | Filter | Sort / Column Limit |
| :----------------------------- | :--------------- | :-------------------------------- | :--------------------------------------------------- |
| **`Shopping TC`** | Board (`Status`) | `label:area:shopping,area:common` | Created (newest first); `Next DTC Agenda` limit: `7` |
| **`Payments TC`** | Board (`Status`) | `label:area:payments` | Created (newest first); `Next DTC Agenda` limit: `7` |
| **`Food TC`** | Board (`Status`) | `label:area:food` | Created (newest first); `Next DTC Agenda` limit: `7` |
| **`Lodging TC`** | Board (`Status`) | `label:area:lodging` | Created (newest first); `Next DTC Agenda` limit: `7` |
| **`Community Spotlight Pool`** | Table | `track:"Community Spotlight"` | `Priority Score` (descending) |

### `Status` Columns

| Column | Color | Purpose |
| :-------------------------- | :----- | :-------------------------------------------------------------------------------------------------------------- |
| **`Triage / Unscheduled`** | Gray | Default intake state set by GitHub Projects' built-in _Item added to project_ workflow. |
| **`Next DTC Agenda`** | Orange | Queued for discussion at the upcoming meeting. |
| **`Approved`** | Green | Approved in the meeting; `gov:tc-meeting` removed and circle-back comment posted once `meeting-minutes` merges. |
| **`Follow-up / Revisions`** | Purple | Direction approved with revisions or follow-up requested. |
| **`Redirected / Declined`** | Red | Redirected to a Domain Working Group / self-hosted extension or declined. |
| **`Closed / Merged`** | Gray | Automatically set by GitHub Projects' built-in _Item closed_ and _Pull request merged_ workflows. |

### Built-in Workflows & Permissions

- **Built-in Project Workflows:**
- _Auto-add to project_: `is:issue,pr is:open label:gov:tc-meeting,community-spotlight`
- _Item added to project_: sets `Status = Triage / Unscheduled`
- _Item closed_ & _Pull request merged_: sets `Status = Closed / Merged`
- _Auto-archive items_: enabled
- **Team Access:** Organization base role `Read`; `@devops-maintainers` granted `Admin`; Domain Technical Council teams (`@shopping-tech-council`, `@payments-tech-council`, `@food-tech-council`, `@lodging-tech-council`) granted `Write`.
- **Scheduled Sync (`.github/workflows/dtc-pipeline.yml`):**
- Every 15 minutes: `sync-agenda-assignees --apply` resolves the Technical Council member who moved each card into `Next DTC Agenda` via `ProjectV2ItemStatusChangedEvent` timeline history, assigns them to the Issue or Pull Request, and stamps `Track = General Track` on open `gov:tc-meeting` items.
- Daily at 06:00 UTC: `scan-spotlight --apply` refreshes Community Spotlight eligibility and syncs `Track = Community Spotlight` and `Priority Score` onto the Project board without applying repository labels on `ucp`.

## Community Spotlight Selection

1. **Gate 1 (External Affiliation):** Excludes members of UCP governance and maintainer teams (`@*-tech-council`, `@governance-council`, `@maintainers`, organization members), companies listed in `MAINTAINERS.md`, matching corporate email domains, and bot accounts.
2. **Gate 2 (Governance Scope):** Bundles linked Proposal Issues and Pull Requests; matches Pull Requests carrying `gov:needs-tc-review` or `gov:tc-meeting`, plus standalone proposal issues carrying `area:<domain>` and a proposal prefix or label.
3. **Gate 3 (Baseline Readiness & Hygiene):** Requires non-draft Pull Requests without merge conflicts, passing contributor license agreement (`cla/google`) and validation checks, or structured proposal issue bodies (`>= 400` characters with template headers), and excludes `status:blocked`, `status:stale`, and `wontfix`.
4. **100-Point Priority Formula (Milestone-Blind):**

$$\text{Priority Score (0–100)} = \text{Readiness (0–40)} + \text{Capped Traction (0–30)} + \text{Wait-Time Boost (0–30)} - \text{Cooldown (0 or 30)}$$

## Usage

```bash
# Run unit tests
uv run python -m unittest discover -s org-tools/dtc-pipeline/tests -v

# Run Community Spotlight scan (read-only preview, or --apply to sync Project v2)
uv run python org-tools/dtc-pipeline/scripts/dtc_pipeline.py scan-spotlight --org Universal-Commerce-Protocol --repo ucp

# Provision or clone a GitHub Project v2 board
uv run python org-tools/dtc-pipeline/scripts/dtc_pipeline.py provision-project \
--owner Universal-Commerce-Protocol --title "DTC Review Pipeline" --public \
--admin-teams devops-maintainers --writer-teams shopping-tech-council

# Restore canonical 5-view filters and visible fields
uv run python org-tools/dtc-pipeline/scripts/dtc_pipeline.py configure-views --project-id PVT_...

# Sync Next DTC Agenda assignees and General Track field
uv run python org-tools/dtc-pipeline/scripts/dtc_pipeline.py sync-agenda-assignees --project-id PVT_... --apply
```
Loading
Loading