[FEATURE] Revamp Docs PR template

[zastrowm]

Revamp Docs PR Template

Overview

The PR template for the strands-agents/docs repository is currently too verbose and contains sections that are frequently left empty or unused. After analyzing 12+ recent merged PRs, we need to create streamlined templates that better match actual contributor usage patterns.

Current Template Issues:

• Too many sections (8 total)
• Sections like "Areas Affected", "Screenshots", and "Additional Notes" are often empty
• Placeholder text "" is frequently not removed
• Checklist items are often left unchecked even when PRs are merged
• Template is too rigid for varied PR types (typo fixes vs major features)

Reference Links:

• Current template: https://github.com/strands-agents/docs/blob/main/.github/PULL_REQUEST_TEMPLATE.md
• Recent merged PRs: https://github.com/strands-agents/docs/pulls?q=is%3Apr+is%3Amerged+

Implementation Requirements

Based on PR analysis and clarification discussion:

Deliverables

Create three new PR template files in .github_temp/PULL_REQUEST_TEMPLATE/:

1. default.md - Main template for general PRs
2. quick-fix.md - Simplified template for typo/formatting fixes
3. feature.md - Template for major feature additions

Template Design Specifications

1. Default Template (default.md)

Required Sections:

• Description & Context (merged section)

  • Include prompt for what changed and why
  • Encourage linking to related issues with Fixes #123 or Related to #123 format

• Type of Change (checkbox format)

  • Use checkboxes (easier to use than text list)
  • Remove placeholder text issue
  • Options: New content, Content update, Structure/organization, Typo/formatting, Bug fix, Other

• Checklist (simplified to 3-4 items)

  • Essential items only with "if applicable" language
  • Example items:
    • I have tested the documentation locally using mkdocs serve (if applicable)
    • Links in the documentation are valid and working
    • My changes follow the project's documentation style
    • All new and existing tests pass (if applicable)

• Licensing Statement (keep as-is)

Sections to Remove:

• Areas Affected (often empty)
• Screenshots (often N/A, contributors can add if needed)
• Additional Notes (often empty)

2. Quick Fix Template (quick-fix.md)

Minimal template for typos, formatting, and small corrections:

• Description - Brief description of fix
• Type of Fix - Simple checkbox: Typo, Formatting, Link fix, Other
• Files Changed - List of affected files
• Checklist (2-3 items max)
  • I have tested locally using mkdocs serve
  • Changes follow documentation style
• Licensing Statement

3. Feature Template (feature.md)

Comprehensive template for new content/major additions:

• Description & Motivation - What and why
• Related Issues - Link to issues/PRs
• Type of Change - Checkboxes for change type
• Content Overview - What pages/sections are being added
• Testing & Validation
  • Tested locally with mkdocs serve
  • All links are valid and working
  • Images/diagrams properly formatted (if applicable)
  • Follows documentation style
  • All tests pass
• Licensing Statement

File Locations

All templates must be created under .github_temp/PULL_REQUEST_TEMPLATE/ directory:

• .github_temp/PULL_REQUEST_TEMPLATE/default.md
• .github_temp/PULL_REQUEST_TEMPLATE/quick-fix.md
• .github_temp/PULL_REQUEST_TEMPLATE/feature.md

Note: Templates are created in .github_temp instead of .github because we don't have permission to push to .github directory directly. These will need to be moved to .github/PULL_REQUEST_TEMPLATE/ when the PR is reviewed.

Usage Instructions

When users create a PR, they can select a template by appending query parameter:

• Default: Auto-selected when no query parameter
• Quick Fix: ?template=quick-fix.md
• Feature: ?template=feature.md

Include a README.md in .github_temp/PULL_REQUEST_TEMPLATE/ explaining:

• What each template is for
• How to select a template
• Instructions for moving templates to .github/PULL_REQUEST_TEMPLATE/ during PR review

Acceptance Criteria

• Three new PR template files created in .github_temp/PULL_REQUEST_TEMPLATE/
• Default template has merged Description & Context section
• All templates use checkbox format for Type of Change (no placeholder text)
• Checklists are simplified to 3-4 essential items with "if applicable" language
• Quick-fix template is minimal and easy to use
• Feature template is comprehensive for major changes
• All sections that are often empty (Areas Affected, Additional Notes) are removed
• Screenshots section is removed (contributors can add manually if needed)
• README.md created explaining template usage and deployment
• All templates include the licensing statement
• Templates are properly formatted and render correctly in markdown

Testing Approach

1. Create the three template files with proper markdown formatting
2. Verify markdown renders correctly by viewing files in GitHub
3. Document how to test templates work correctly (requires actual PR creation to verify)
4. Include instructions in README for final validation after templates are moved to .github/ directory

Technical Notes

• Repository: strands-agents/docs (this work is for that repo, not sdk-python)
• Language: Markdown
• No code changes: Pure documentation/template work
• No automated tests needed: Manual validation via PR creation
• Cross-repo context: Many docs PRs reference sdk-python issues, templates should support this pattern

Documentation Updates

Consider adding to the docs repository's CONTRIBUTING.md:

• Brief mention of multiple PR template options
• Guidance on which template to use for different PR types
• Link to template README for detailed instructions

This will help prevent future confusion and improve contributor experience.

[zastrowm]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

Repository Analysis

I've analyzed both PR templates and reviewed 12+ recent merged PRs from the strands-agents/docs repository to understand usage patterns.

Current State

strands-agents/docs template (666 bytes):

• Description
• Type of Change (6 options + placeholder text)
• Motivation and Context
• Areas Affected
• Screenshots
• Checklist (6 items)
• Additional Notes
• Licensing statement

zastrowm/sdk-python template (1198 bytes):

• Description
• Related Issues
• Documentation PR
• Type of Change (5 options)
• Testing (with specific commands)
• Checklist (6 items)
• Licensing statement

Key Findings from PR Analysis

From reviewing recent merged PRs in docs repo:

Consistently Used Sections:

• ✅ Description - Always filled, high value
• ✅ Type of Change - Usually filled
• ✅ Motivation and Context - Frequently includes issue links

Problematic Sections:

• ⚠️ Areas Affected - Often left empty or minimal
• ⚠️ Screenshots - Often N/A for text/code changes
• ⚠️ Additional Notes - Frequently empty
• ⚠️ Checklist - Items often left unchecked even when PR is merged
• ⚠️ Placeholder text "" frequently not removed

Observed Patterns:

• Many PRs reference issues from strands-agents/sdk-python (cross-repo coordination)
• Contributors sometimes customize template or deviate from structure
• Template appears too rigid for varied PR types (typo fixes vs major features)

---

Clarifying Questions

1. Repository Scope

Which repository should be updated?

• The issue is filed in zastrowm/sdk-python but references the strands-agents/docs PR template
• Should changes be made to:
  • Only strands-agents/docs repository?
  • Only zastrowm/sdk-python repository?
  • Both repositories?

2. Template Unification

Should both repositories use the same template?

• The sdk-python template is code-focused (testing commands, docs PR link)
• The docs template is documentation-focused (motivation, screenshots)
• Should they remain different or be unified?

3. Simplification Priorities

Based on the analysis, which sections should be kept/removed/simplified?

Consider removing or making optional:

• "Areas Affected" - often left empty
• "Screenshots" - often N/A for code/text changes
• "Additional Notes" - frequently empty

Consider keeping:

• Description
• Type of Change
• Motivation and Context (valuable for issue linking)
• Checklist (though perhaps simplified)

4. Type of Change Format

How should "Type of Change" be structured?

• Current docs version: Text list with placeholder that's often not removed
• Current sdk-python version: Checkbox format with instruction to "delete the rest"
• Should it be:
  • Checkboxes (easier to use)?
  • Dropdown/radio (if GitHub supports)?
  • Free text field?

5. Template Variants

Should there be different templates for different PR types?

• GitHub supports multiple PR templates
• Could have: quick-fix.md, feature.md, documentation.md
• Or keep single simplified template?

6. Checklist Approach

How should the checklist be handled?

• Many PRs have unchecked items even when merged
• Options:
  • Simplify to 3-4 essential items
  • Make all items optional with "if applicable" language
  • Remove checklist entirely
  • Keep as-is

7. Implementation Location

Where should the new template file be created?

• Note: I don't have permission to push directly to .github/ directory
• Options:
  • Create under .github_temp/ directory (per SOP)
  • Provide template content for manual placement
  • Create PR with template change directly

---

Recommendations

Based on the analysis, I recommend:

1. Simplify to essential sections only: Description, Type of Change (checkboxes), Related Issues, Brief Checklist
2. Remove: Areas Affected, Additional Notes, Screenshots (or make explicitly optional)
3. Improve Type of Change: Use checkbox format without placeholder text
4. Streamline Checklist: 3-4 essential items with "if applicable" language
5. Consider: Creating separate quick-fix template for typos/small changes

Please provide your feedback on these questions so I can create an appropriate implementation plan.

[zastrowm]

/strands

Repository Analysis & Clarifying Questions

Key Findings from PR Analysis

Observed Patterns:

• Many PRs reference issues from strands-agents/sdk-python (cross-repo coordination)
• Contributors sometimes customize template or deviate from structure
• Template appears too rigid for varied PR types (typo fixes vs major features)

Clarifying Questions

1. Repository Scope

Which repository should be updated?

• The issue is filed in zastrowm/sdk-python but references the strands-agents/docs PR template

• Should changes be made to:

  • Only strands-agents/docs repository?
  • Only zastrowm/sdk-python repository?
  • Both repositories?

strands-agents/docs

2. Template Unification

Should both repositories use the same template?

• The sdk-python template is code-focused (testing commands, docs PR link)
• The docs template is documentation-focused (motivation, screenshots)
• Should they remain different or be unified?

3. Simplification Priorities

Based on the analysis, which sections should be kept/removed/simplified?

Consider removing or making optional:

• "Areas Affected" - often left empty
• "Screenshots" - often N/A for code/text changes
• "Additional Notes" - frequently empty

Consider keeping:

• Description
• Type of Change
• Motivation and Context (valuable for issue linking)
• Checklist (though perhaps simplified)

Simplify checklist; merge Description & Context

4. Type of Change Format

How should "Type of Change" be structured?

• Current docs version: Text list with placeholder that's often not removed

• Current sdk-python version: Checkbox format with instruction to "delete the rest"

• Should it be:

  • Checkboxes (easier to use)?
  • Dropdown/radio (if GitHub supports)?
  • Free text field?

5. Template Variants

Should there be different templates for different PR types?

• GitHub supports multiple PR templates
• Could have: quick-fix.md, feature.md, documentation.md
• Or keep single simplified template?

Multiple - as you suggested

6. Checklist Approach

How should the checklist be handled?

• Many PRs have unchecked items even when merged

• Options:

  • Simplify to 3-4 essential items
  • Make all items optional with "if applicable" language
  • Remove checklist entirely
  • Keep as-is

Simplify to 3-4 essential items

7. Implementation Location

Where should the new template file be created?

• Note: I don't have permission to push directly to .github/ directory

• Options:

  • Create under .github_temp/ directory (per SOP)
  • Provide template content for manual placement
  • Create PR with template change directly

`.github_temp

Recommendations

Based on the analysis, I recommend:

1. Simplify to essential sections only: Description, Type of Change (checkboxes), Related Issues, Brief Checklist
2. Remove: Areas Affected, Additional Notes, Screenshots (or make explicitly optional)
3. Improve Type of Change: Use checkbox format without placeholder text
4. Streamline Checklist: 3-4 essential items with "if applicable" language
5. Consider: Creating separate quick-fix template for typos/small changes

Please provide your feedback on these questions so I can create an appropriate implementation plan.

Sounds good

[github-actions]

Task Refinement Complete

Summary

I've successfully refined issue #7 and updated the issue description with comprehensive implementation requirements.

What Was Accomplished

Research & Analysis

• ✅ Analyzed current PR templates for both strands-agents/docs and zastrowm/sdk-python repositories
• ✅ Reviewed 12+ recent merged PRs from strands-agents/docs to identify usage patterns
• ✅ Identified problematic sections that are frequently left empty (Areas Affected, Screenshots, Additional Notes)
• ✅ Compared template structures between code and documentation repositories

Clarifications Obtained

• Target Repository: strands-agents/docs only
• Approach: Create multiple template variants (default, quick-fix, feature)
• Simplifications: Merge Description & Context, simplify checklist to 3-4 items
• Location: Templates will be created in .github_temp/PULL_REQUEST_TEMPLATE/ directory

Issue Description Updated

The issue now includes:

• Clear overview of the problem and context
• Detailed specifications for three template variants
• Specific file locations and naming conventions
• Complete acceptance criteria (12 checkpoints)
• Testing approach and validation steps
• Technical notes about repository context
• Recommendations for CONTRIBUTING.md updates

Implementation Readiness

✅ This issue is ready for implementation

The task is well-scoped for a single developer to complete in a few hours:

• Complexity: Low - Markdown file creation with clear specifications
• Files to Create: 4 files (3 templates + 1 README)
• Dependencies: None
• Testing: Manual validation via markdown rendering and PR creation
• Estimated Effort: 2-4 hours

Key Implementation Details

1. Create three distinct PR templates catering to different use cases
2. Default template merges Description & Context, uses checkboxes for Type of Change
3. Quick-fix template is minimal for small corrections
4. Feature template is comprehensive for major additions
5. All templates have simplified 3-4 item checklists with "if applicable" language
6. README.md explains template selection and deployment process

Next Steps

A developer can now:

1. Review the updated issue description
2. Create the three template files based on specifications
3. Add README with usage instructions
4. Test markdown rendering
5. Create PR with the new templates for review

The implementation path is clear and all ambiguities have been resolved.

[zastrowm]

/strands implement