Skip to content

post_publish_warning_examples.md

Latest commit

 

History

History
198 lines (129 loc) · 13.1 KB

post_publish_warning_examples.md

File metadata and controls

198 lines (129 loc) · 13.1 KB
Raw

Post-Publish Warning Examples

Use this page when post-publish checks or GitHub readiness checks produce warnings. Read it with docs/post_publish_checklist.md, docs/published_repository_status.md, docs/public_maintainer_status_update_examples.md, docs/issue_template_stale_evidence_examples.md, docs/github_release_commands.md, docs/release_note_refresh_checklist.md, docs/github_latest_release_troubleshooting_examples.md, docs/release_asset_upload_dry_run_examples.md, docs/release_asset_checksum_mismatch_examples.md, docs/github_release_attachment_screenshot_checklist.md, docs/stale_release_page_screenshot_examples.md, docs/github_authenticated_maintenance_troubleshooting_examples.md, docs/github_public_pr_api_fallback_troubleshooting_examples.md, docs/github_api_rate_limit_troubleshooting_examples.md, docs/github_repository_metadata_troubleshooting_examples.md, docs/stale_repository_topics_evidence_examples.md, docs/github_repository_settings_screenshot_checklist.md, docs/stale_branch_protection_screenshot_examples.md, docs/dependabot_secret_scanning_verification_examples.md, docs/stale_dependabot_alert_evidence_examples.md, docs/launch_feedback_collection_examples.md, docs/stale_launch_feedback_claim_examples.md, docs/stale_github_discussions_pin_examples.md, docs/social_preview_verification_examples.md, docs/stale_social_preview_cache_examples.md, docs/profile_pin_verification_examples.md, docs/stale_profile_pin_evidence_examples.md, docs/github_actions_warning_examples.md, docs/github_actions_badge_verification_examples.md, docs/stale_github_actions_badge_cache_examples.md, and docs/command_output_troubleshooting_map.md.

The core rule: local quality evidence and remote GitHub evidence prove different things. Do not claim published evidence until the remote checks pass, and do not treat GitHub warning rows as local code failures unless strict launch verification is required.

Expected Evidence Split

Local proof before push:

python -B scripts/dev.py quality
python -B scripts/dev.py fresh-clone-local

Remote proof after push:

python -B scripts/dev.py fresh-clone
python -B scripts/post_publish_check.py
python -B scripts/dev.py github-readiness

Use python -B scripts/check_github_readiness.py --strict only when account-level setup is expected to be finished and manual warning rows should block the release claim.

Remote File Lag

Symptom:

  • Local main is ahead of origin/main.
  • fresh-clone-local passes but fresh-clone or post_publish_check.py still reads older remote files.
  • A newly linked doc is present locally but missing on GitHub.

Wrong fix:

  • Treat local clone proof as remote publication proof.
  • Remove the new file from post-publish checks.
  • Claim the public branch has the new docs before push.

Safe fix:

git status --short --branch
git rev-parse HEAD
git ls-remote origin refs/heads/main
python -B scripts/dev.py fresh-clone-local

After the push is intentionally visible:

python -B scripts/dev.py fresh-clone
python -B scripts/post_publish_check.py

Raw README Failures

Symptom:

  • post_publish_check.py fails on raw README reachability.
  • The GitHub page is reachable, but raw content returns a transient error or stale content.
  • A README link appears locally but the raw remote branch has not caught up.

Wrong fix:

  • Weaken README links to make the check pass.
  • Treat a raw README failure as proof that local docs are wrong.

Safe fix:

python -B scripts/post_publish_check.py
python -B scripts/dev.py fresh-clone

If the failure repeats after the pushed branch is visible, inspect the exact raw URL and file path named by the check. Keep README claims conservative until the raw file is reachable.

GitHub Actions Pending State

Symptom:

  • github-readiness reports a pending quality-gate.
  • The local quality command passed.
  • GitHub Actions has not finished processing the latest pushed commit.

Wrong fix:

  • Mark GitHub Actions as green because local quality passed.
  • Delete the readiness row or lower the expected check name.

Safe fix:

python -B scripts/dev.py quality
python -B scripts/dev.py github-readiness

If the latest pushed commit is still pending, wait for Actions and rerun readiness. Local quality is useful evidence, but it is not a replacement for the remote workflow result.

Use docs/github_actions_badge_verification_examples.md when the README badge, Actions page, and current github-readiness output disagree.

Use docs/stale_github_actions_badge_cache_examples.md before treating old badge images, wrong workflow badge URLs, skipped workflow badges, fork-PR badge confusion, or private account UI crops as current workflow evidence.

Use docs/dependabot_secret_scanning_verification_examples.md before treating Dependabot alerts, Dependabot security updates, secret scanning, push protection, or local safety-scan output as repository security-setting evidence.

Use docs/stale_dependabot_alert_evidence_examples.md before treating old security alert screenshots, wrong dependency scopes, dismissed alert rows, private security-tab crops, or local safety-scan output as current repository security-setting evidence.

Readiness Warning Rows

Symptom:

  • github-readiness exits with 0 failure(s) but reports [WARN] rows for metadata, topics, branch protection, release page state, or API rate limits.
  • A reviewer asks whether the local docs change is blocked.

Wrong fix:

  • Treat every warning as a code failure.
  • Treat every warning as completed account setup.
  • Hide the warning in status docs.

Safe fix:

python -B scripts/dev.py github-readiness
python -B scripts/dev.py launch-assets

Non-strict warnings mean account-level or remote-freshness follow-up. Use docs/github_latest_release_troubleshooting_examples.md for latest-release state, tag selection, draft/prerelease confusion, and artifact drift. Use docs/github_authenticated_maintenance_troubleshooting_examples.md for dry-run versus apply, account permissions, branch protection or release side effects, and PR maintenance safeguards. Use docs/github_api_rate_limit_troubleshooting_examples.md for API rate limits, transient failures, stale cached status, pending Actions lookups, and strict-mode review. Use docs/github_repository_metadata_troubleshooting_examples.md for description, topics, URL, stale public status, and unauthenticated maintenance warnings. Strict warnings block claims that GitHub setup is finished.

Manual Account Settings

Symptom:

  • github-readiness prints [MANUAL] social preview configured.
  • github-readiness prints [MANUAL] profile repository pin configured.
  • Repository metadata, topics, branch protection, or release page work remains listed under manual follow-up.

Wrong fix:

  • Claim full GitHub setup from local checks.
  • Mark manual rows done before using the GitHub UI or authenticated maintenance path.

Safe fix:

python -B scripts/dev.py github-maintenance
python -B scripts/dev.py github-readiness

Use docs/github_repository_settings.md for the expected account settings, docs/github_repository_settings_screenshot_checklist.md before retaining or sharing settings screenshots, docs/social_preview_verification_examples.md before treating social preview image checks as account-level setup evidence, and docs/profile_pin_verification_examples.md before treating profile-page state as complete. Keep manual rows visible until the account action is done and rechecked.

Use docs/launch_feedback_collection_examples.md before treating stars, forks, public comments, private messages, or analytics screenshots as launch-feedback evidence.

Use docs/stale_launch_feedback_claim_examples.md before treating stale feedback counts, stale comments, private feedback summaries, analytics screenshots, or launch-post reposts as current public evidence.

Use docs/stale_github_discussions_pin_examples.md before treating global pins, category pins, starter topics, wrong-category links, or old launch-feedback discussion references as current public evidence.

Use docs/stale_repository_topics_evidence_examples.md before treating old topic screenshots, wrong topic slugs, unauthenticated API warning rows, cached repository cards, or private account UI crops as current repository-topic evidence.

Use docs/stale_branch_protection_screenshot_examples.md before treating old branch-rule screenshots, wrong branch names, API warning rows, inherited organization policy screenshots, or private account UI crops as current branch-protection evidence.

Use docs/github_release_attachment_screenshot_checklist.md before treating screenshots of replay artifact attachments, missing attachments, wrong tags, or latest-release attachment state as release evidence.

Use docs/stale_release_page_screenshot_examples.md before treating old release-page screenshots, stale latest-release screenshots, missing attachment screenshots, wrong-tag screenshots, or private account UI crops as current release evidence.

Use docs/stale_social_preview_cache_examples.md before treating old social-preview images, wrong uploaded images, cache delays, profile-pin confusion, or private account UI crops as current social-preview evidence.

Use docs/stale_profile_pin_evidence_examples.md before treating old profile screenshots, wrong pinned repositories, stale profile caches, social-preview confusion, or private account UI crops as current profile-pin evidence.

Use docs/release_note_refresh_checklist.md before treating checked-in release notes, GitHub release-page text, replay artifacts, or post-publish evidence as current release evidence.

Use docs/release_asset_upload_dry_run_examples.md before treating a release asset upload dry-run, generated out/ files, or a local replay artifact as uploaded GitHub release evidence.

Use docs/release_asset_checksum_mismatch_examples.md before treating local hashes, changed generated artifact hashes, screenshot-visible attachments, or public release attachments as current release evidence.

Use docs/public_maintainer_status_update_examples.md before summarizing warnings or manual rows in a public maintainer update.

Use docs/issue_template_stale_evidence_examples.md before editing issue templates or seeded issue bodies that ask contributors for command output, screenshots, generated artifacts, account-level evidence, or roadmap evidence.

Review Checklist

  • Local quality and fresh-clone-local passed before push-facing work.
  • Remote fresh-clone and post_publish_check.py passed after push.
  • GitHub readiness has no hard failures.
  • [WARN] and [MANUAL] rows are described as follow-up unless strict verification is required.
  • Public docs do not claim remote files, release page state, branch protection, social preview, profile pin, or launch feedback before matching evidence exists.
  • Public maintainer updates keep local quality, pushed code, remote GitHub evidence, account-level/manual setup, and roadmap promises separate.
  • Issue templates ask for current reproducible evidence and do not request stale output, private screenshots, local machine details, generated artifacts as source, or account-level material.
  • Stale launch-feedback claims are reviewed before public docs mention old stars, forks, public comments, private feedback summaries, analytics screenshots, or launch-post reposts.
  • Stale GitHub Discussions pins are reviewed before public docs claim global pins, category pins, starter topics, wrong-category links, or old launch-feedback discussion references are current.
  • Stale repository-topic evidence is reviewed before public docs claim old topic screenshots, wrong topic slugs, unauthenticated API warning rows, cached repository cards, or private account UI crops are current.
  • Stale branch-protection screenshots are reviewed before public docs claim old branch-rule screenshots, wrong branch names, API warning rows, inherited organization policy screenshots, or private account UI crops are current.
  • Stale Dependabot alert evidence is reviewed before public docs claim old security alert screenshots, wrong dependency scopes, dismissed alert rows, private security-tab crops, or local safety-scan output are current.
  • Stale GitHub Actions badge cache evidence is reviewed before public docs claim old badge images, wrong workflow badge URLs, skipped workflow badges, fork-PR badge confusion, or private account UI crops are current.
  • Stale release-page screenshots are reviewed before public docs claim old release-page screenshots, stale latest-release screenshots, missing attachment screenshots, wrong-tag screenshots, or private account UI crops are current.
  • Stale social-preview cache evidence is reviewed before public docs claim old social-preview images, wrong uploaded images, cache delays, profile-pin confusion, or private account UI crops are current.
  • Stale profile-pin evidence is reviewed before public docs claim old profile screenshots, wrong pinned repositories, stale profile caches, social-preview confusion, or private account UI crops are current.
  • Release asset checksum mismatches are reviewed before public docs claim release attachments, screenshots, or hashes are current.