Require screenshot/video for documentation PRs to ensure local verification

[tanupriyasingh1]

Problem

With the growing use of AI tools among contributors, there is a risk of
documentation changes being submitted without ever being run or verified
locally. This can lead to broken or incorrect documentation slipping
through during review, and puts unnecessary burden on maintainers to
catch these issues manually.

Proposed Solution

Make it mandatory for contributors to attach a screenshot or short screen
recording whenever a PR includes documentation changes. This ensures:

• The contributor has actually run the docs locally before submitting
• Reviewers can do a quick visual check before diving into the code
• Low-effort or AI-generated doc PRs are easier to catch and reject early

Implementation Plan

1. CI Check — Blocks Merge if No Media Attached

Create .github/workflows/docs-media-check.yml

A GitHub Actions workflow that:

• Triggers on every PR open, edit, or sync
• Detects if any docs/ or .md / .mdx files were changed
• Scans the PR description for an image or video attachment
• Fails the CI check if doc files are changed but no media is found
• Passes and allows merge if media is attached

This is the core enforcement mechanism — no screenshot/video means
the PR cannot be merged.

2. Bot Comment — Guides Contributors Automatically

Create .github/workflows/docs-pr-comment.yml

A GitHub Actions bot that:

• Triggers when a doc-related PR is opened
• Posts an automatic comment tagging the contributor
• Explains the screenshot/video requirement clearly
• Links to the contributing guide for running docs locally

This ensures contributors understand the requirement immediately
without needing a maintainer to manually explain it.

Benefits

• Zero manual effort from maintainers to enforce this
• New contributors are guided automatically via bot comment
• Scales well as contributor count grows
• Acts as a soft filter against AI-generated or untested doc PRs

Additional Notes

This is a proactive measure to maintain documentation quality
as AI-assisted contributions become more common in open source.
The goal is not to discourage contributions, but to ensure every
doc change is actually verified before merging.

[Ayushmore1214]

@tanupriyasingh1 liked your idea, but we don't need 2 workflows for this its overengineering for our project, running a scan on every PR just to check an image is a waste of github actions mins, and bot commenting on on every PR can become noisy

[Ayushmore1214]

What we can do is update the PULL_REQUEST_TEMPLATE.md and add a section asking for if its a doc or site related change plz attach screenshots and videos accordingly, if the contributor ignores the template we can ask him to do so, lets keep our CI clean and avoid overcomplicated solutions!

[Ayushmore1214]

@eeshaanSA @rahulshendre drop your views on this!!

[Ayushmore1214]

Thinking of AI generated PR's we can add something like this in our contributing guide : https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md#ai-use-policy-and-guidelines

[rahulshendre]

Thinking of AI generated PR's we can add something like this in our contributing guide : https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md#ai-use-policy-and-guidelines

yes and we could also refer this https://www.kubernetes.dev/docs/guide/pull-requests/#ai-guidance

[rahulshendre]

@eeshaanSA @rahulshendre drop your views on this!!

Agreed @Ayushmore1214, PR template is the way to go, its simple and keeps CI clean

[Ayushmore1214]

@tanupriyasingh1 Lets go with updating the PR template for now, assigning it to you