From 859f0cfb6a51a0441403ef157001186a25b0a002 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Jul 2026 20:55:51 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=A8=20chore:=20remove=20CodeQL=20and?= =?UTF-8?q?=20Jules=20outdated-docs=20workflows?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Template-consistency cleanup: - Delete .github/workflows/codeql.yml (CodeQL scanning) - Delete .github/workflows/jules-find-outdated-docs.yml and its orphaned OUTDATED_DOCUMENTATION_GUIDELINE.md guideline - Drop the jules-find-outdated-docs.yml entry from onboard.py's Jules workflow toggle list Leaves jules-prune-unnecessary-code.yml and jules-sync-translations.yml intact. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_016dd3AfUTtAi9FokMUZSiZJ --- .github/workflows/codeql.yml | 40 --- .../workflows/jules-find-outdated-docs.yml | 228 ------------------ OUTDATED_DOCUMENTATION_GUIDELINE.md | 87 ------- onboard.py | 4 - 4 files changed, 359 deletions(-) delete mode 100644 .github/workflows/codeql.yml delete mode 100644 .github/workflows/jules-find-outdated-docs.yml delete mode 100644 OUTDATED_DOCUMENTATION_GUIDELINE.md diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml deleted file mode 100644 index b382d12..0000000 --- a/.github/workflows/codeql.yml +++ /dev/null @@ -1,40 +0,0 @@ -name: "CodeQL" - -on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - schedule: - - cron: '34 20 * * 1' - -jobs: - analyze: - name: Analyze - runs-on: ubuntu-latest - permissions: - actions: read - contents: read - security-events: write - - strategy: - fail-fast: false - matrix: - language: [ 'javascript-typescript', 'python' ] - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Initialize CodeQL - uses: github/codeql-action/init@v4 - with: - languages: ${{ matrix.language }} - - - name: Autobuild - uses: github/codeql-action/autobuild@v4 - - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4 - with: - category: "/language:${{matrix.language}}" diff --git a/.github/workflows/jules-find-outdated-docs.yml b/.github/workflows/jules-find-outdated-docs.yml deleted file mode 100644 index af9cd40..0000000 --- a/.github/workflows/jules-find-outdated-docs.yml +++ /dev/null @@ -1,228 +0,0 @@ -# ───────────────────────────────────────────────────────────────────── -# Jules Outdated Documentation Drift Detection -# ───────────────────────────────────────────────────────────────────── -# Automated weekly documentation drift check via Jules API. Runs every -# Wednesday at 4pm UTC and on manual dispatch. Opens a PR with -# any corrections. -# -# Jules reads OUTDATED_DOCUMENTATION_GUIDELINE.md before making changes. -# -# Required secrets: JULES_API_KEY -# ───────────────────────────────────────────────────────────────────── -name: Jules Find Outdated Docs - -on: - schedule: - - cron: "0 16 * * 3" # Wednesday 4pm UTC - workflow_dispatch: - -permissions: - contents: read - actions: read - -concurrency: - group: jules-find-outdated-docs - cancel-in-progress: false - -env: - JULES_API_BASE: "https://jules.googleapis.com/v1alpha" - MAX_POLL_ATTEMPTS: 60 - POLL_INTERVAL_SECONDS: 30 - -jobs: - find-outdated-docs: - name: Detect and fix outdated documentation via Jules - runs-on: ubuntu-latest - timeout-minutes: 45 - - steps: - # ── 1. Checkout ─────────────────────────────────────────────── - - name: Checkout repository - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - # ── 2. Create Jules documentation drift session ─────────────── - - name: Create Jules documentation drift session - id: jules-create - env: - JULES_API_KEY: ${{ secrets.JULES_API_KEY }} - run: | - set -euo pipefail - - if [[ -z "${JULES_API_KEY:-}" ]]; then - echo "::error::JULES_API_KEY is not configured. Add it in repository Actions secrets." - exit 1 - fi - - REPO="${{ github.repository }}" - OWNER="${REPO%%/*}" - REPO_NAME="${REPO##*/}" - SOURCE="sources/github/${OWNER}/${REPO_NAME}" - - PROMPT="IMPORTANT: Before you begin, read the file OUTDATED_DOCUMENTATION_GUIDELINE.md in the root of this repository. - It contains the rules and validation requirements you must follow strictly when detecting - and fixing outdated documentation. - - Also read docs/translation-guide.md if it exists, to understand the translation policy. - Any documentation changes you make must respect the translation workflow - only edit English - source files, never edit translation files directly. - - You are a documentation maintenance assistant for this project. - - Scan the repository for documentation drift including: - - README.md sections that no longer match actual project behavior - - CLAUDE.md instructions that reference moved, renamed, or deleted files - - Docstrings that describe outdated function signatures or behavior - - Code examples in docs that use deprecated APIs or patterns - - Configuration references that point to renamed or removed settings - - Broken internal cross-references between documentation files - - Changelog entries that reference incorrect versions or dates - - Install/setup instructions that skip required steps or list wrong commands - - Strict rules - you MUST follow every one: - 1. Follow ALL rules in OUTDATED_DOCUMENTATION_GUIDELINE.md without exception. - 2. Only fix documentation that is verifiably incorrect by cross-referencing the actual code. - 3. Do NOT rewrite documentation style, tone, or structure - only fix factual inaccuracies. - 4. Do NOT add new documentation sections - only update existing content. - 5. Do NOT modify translation files (*.lang.mdx, meta.lang.json) - only English sources. - 6. For each fix, include the evidence (file path and line) showing why the doc is wrong. - 7. Preserve all existing formatting, heading levels, and link structures. - 8. If a referenced file was moved, update the path. If deleted, note the removal clearly. - 9. Group related fixes into logical commits with clear messages. - 10. If no outdated documentation is found, do not create a PR." - - TITLE="docs: fix outdated documentation (automated weekly drift check)" - - BODY=$(jq -n \ - --arg prompt "$PROMPT" \ - --arg title "$TITLE" \ - --arg source "$SOURCE" \ - '{ - prompt: $prompt, - title: $title, - automationMode: "AUTO_CREATE_PR", - sourceContext: { - source: $source, - githubRepoContext: { - startingBranch: "main" - } - } - }') - - MAX_RETRIES=3 - RETRY_DELAY=5 - - for attempt in $(seq 1 "$MAX_RETRIES"); do - HTTP_CODE=$(curl -s -o /tmp/jules_response.json -w "%{http_code}" \ - -X POST \ - -H "Content-Type: application/json" \ - -H "X-Goog-Api-Key: ${JULES_API_KEY}" \ - -d "$BODY" \ - "${JULES_API_BASE}/sessions") - - if [[ "$HTTP_CODE" -ge 200 && "$HTTP_CODE" -lt 300 ]]; then - break - elif [[ "$HTTP_CODE" -ge 500 && $attempt -lt $MAX_RETRIES ]]; then - echo "::warning::Jules API returned ${HTTP_CODE} - retrying in ${RETRY_DELAY}s (attempt ${attempt}/${MAX_RETRIES})" - sleep "$RETRY_DELAY" - RETRY_DELAY=$((RETRY_DELAY * 2)) - else - echo "::error::Jules session creation failed with HTTP ${HTTP_CODE}" - cat /tmp/jules_response.json - exit 1 - fi - done - - SESSION_NAME=$(jq -r '.name' /tmp/jules_response.json) - SESSION_URL=$(jq -r '.url // empty' /tmp/jules_response.json) - - if [[ -z "$SESSION_NAME" || "$SESSION_NAME" == "null" ]]; then - echo "::error::No session name in Jules response" - cat /tmp/jules_response.json - exit 1 - fi - - { - echo "session_name<> "$GITHUB_OUTPUT" - - echo "Jules session created: ${SESSION_NAME}" - echo "Jules UI: ${SESSION_URL}" - - # ── 3. Poll until Jules finishes ────────────────────────────── - - name: Poll Jules session until completion - id: jules-poll - env: - JULES_API_KEY: ${{ secrets.JULES_API_KEY }} - JULES_SESSION_NAME: ${{ steps.jules-create.outputs.session_name }} - run: | - set -euo pipefail - - SESSION_NAME="$JULES_SESSION_NAME" - MAX_ATTEMPTS="$MAX_POLL_ATTEMPTS" - INTERVAL="$POLL_INTERVAL_SECONDS" - - echo "Polling ${SESSION_NAME} (max ${MAX_ATTEMPTS} x ${INTERVAL}s)" - - for attempt in $(seq 1 "$MAX_ATTEMPTS"); do - RETRY_DELAY=5 - for retry in 1 2 3; do - HTTP_CODE=$(curl -s -o /tmp/jules_session.json -w "%{http_code}" \ - -H "X-Goog-Api-Key: ${JULES_API_KEY}" \ - "${JULES_API_BASE}/${SESSION_NAME}") - - if [[ "$HTTP_CODE" -ge 200 && "$HTTP_CODE" -lt 300 ]]; then - break - elif [[ $retry -lt 3 ]]; then - echo "::warning::Poll returned ${HTTP_CODE} - retry ${retry}/3 in ${RETRY_DELAY}s" - sleep "$RETRY_DELAY" - RETRY_DELAY=$((RETRY_DELAY * 2)) - else - echo "::error::Failed to poll session after 3 retries (HTTP ${HTTP_CODE})" - exit 1 - fi - done - - STATE=$(jq -r '.state // "UNKNOWN"' /tmp/jules_session.json) - echo "[${attempt}/${MAX_ATTEMPTS}] state=${STATE}" - - case "$STATE" in - COMPLETED) - PR_URL=$(jq -r '.outputs[0].pullRequest.url // empty' /tmp/jules_session.json) - PR_TITLE=$(jq -r '.outputs[0].pullRequest.title // empty' /tmp/jules_session.json) - - { - echo "jules_state<> "$GITHUB_OUTPUT" - - echo "Session completed. PR: ${PR_URL}" - exit 0 - ;; - FAILED) - echo "jules_state=FAILED" >> "$GITHUB_OUTPUT" - echo "::error::Jules session ended in FAILED state" - jq '.' /tmp/jules_session.json - exit 1 - ;; - esac - - sleep "$INTERVAL" - done - - echo "jules_state=TIMEOUT" >> "$GITHUB_OUTPUT" - echo "::error::Timed out after ${MAX_ATTEMPTS} poll attempts" - exit 1 diff --git a/OUTDATED_DOCUMENTATION_GUIDELINE.md b/OUTDATED_DOCUMENTATION_GUIDELINE.md deleted file mode 100644 index d728c4f..0000000 --- a/OUTDATED_DOCUMENTATION_GUIDELINE.md +++ /dev/null @@ -1,87 +0,0 @@ -# Outdated Documentation Guideline - -This document defines the rules Jules must follow when detecting and fixing -documentation drift in this repository. - -## Philosophy - -Documentation must accurately reflect the current state of the code. We fix -**factual inaccuracies only** - never rewrite style, tone, or structure. Every -fix must be backed by concrete evidence from the codebase. - -## What Counts as Outdated Documentation - -- **Wrong file paths**: References to files or directories that have been moved, - renamed, or deleted. -- **Incorrect commands**: CLI commands, Make targets, or setup instructions that - no longer work as described. -- **Stale API references**: Docstrings or docs describing function signatures, - parameters, or return types that no longer match the actual code. -- **Deprecated patterns**: Code examples showing usage patterns that have been - replaced (e.g., `datetime.utcnow()` instead of `datetime.now(timezone.utc)`). -- **Wrong configuration keys**: References to config keys that have been renamed - or removed from `global_config.yaml` or `pyproject.toml`. -- **Broken cross-references**: Internal links between docs that point to - non-existent anchors or files. -- **Incorrect version requirements**: Python version, dependency versions, or - tool versions that don't match `pyproject.toml`. - -## What Is NOT Outdated Documentation - -Do **not** flag or modify: - -- **Style preferences**: Wording choices, tone, or paragraph structure. -- **Aspirational content**: Roadmap items, planned features, or TODOs. -- **External links**: Links to third-party sites (these are checked by - `make lint_links` separately). -- **Translation files**: Never edit `*.lang.mdx` or `meta.lang.json` files - directly. The Jules Translation Sync workflow handles translations - automatically when English sources change. -- **Generated content**: Auto-generated API docs, badges, or CI status lines. - -## Translation Policy Alignment - -This repository uses an automated Jules Translation Sync workflow. When you -fix English documentation: - -1. **Only edit English source files** (e.g., `file.mdx`, not `file.ja.mdx`). -2. **Never create or modify translation files** - the translation workflow will - pick up your English changes and translate them automatically. -3. **Preserve frontmatter and MDX structure** exactly as-is so translations - remain aligned. -4. If you find a translation file that is outdated relative to its English - source, note it in the PR description but do **not** fix it directly. - -## Files to Scan - -Priority order for drift detection: - -1. `README.md` - Primary entry point, most visible. -2. `CLAUDE.md` - Agent instructions, must match actual project structure. -3. `docs/content/**/*.mdx` - English documentation pages only. -4. `AGENTS.md` - Agent configuration, if present. -5. Docstrings in `src/`, `common/`, `utils/` - Inline documentation. -6. `pyproject.toml` description and metadata fields. - -## Validation Before Fixing - -For each documentation fix, verify: - -1. **Cross-reference the code**: Confirm the actual current behavior by reading - the relevant source file. Never guess. -2. **Check git history**: If a file was recently moved, use the new path. If - deleted, note the removal. -3. **Test commands**: For CLI/Make instructions, verify the command exists in the - Makefile or CLI entry point. -4. **Config key existence**: For config references, verify the key exists in the - current `global_config.yaml` or relevant config file. - -## PR Requirements - -- Title format: `docs: fix outdated documentation (automated weekly drift check)` -- Each fix must be listed in the PR description with: - - File path and line range - - What was wrong (old content) - - What was fixed (new content) - - Evidence file path showing the correct information -- If no outdated documentation is found, do **not** create a PR. diff --git a/onboard.py b/onboard.py index 75743ff..330962a 100644 --- a/onboard.py +++ b/onboard.py @@ -544,10 +544,6 @@ def media() -> None: "jules-prune-unnecessary-code.yml", "Dead code cleanup (Wednesdays 2pm UTC)", ), - ( - "jules-find-outdated-docs.yml", - "Documentation drift check (Wednesdays 4pm UTC)", - ), ] _WORKFLOWS_DIR = PROJECT_ROOT / ".github" / "workflows"