PORTN-3235 Map prs to service in a monorepo guide

[kodjomiles]

Description

Added a documentation that guides the user on how to map prs to services in a monorepo

Added docs pages

Please also include the path for the added docs

-Map PR's to services in a monorepo (/guides/all/map-prs-to-services-in-monorepo)

[notion-workspace]

Docs - map PRs to service in a monorepo

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2666.d2ngvl90zqbob8.amplifyapp.com

[claude]

Claude finished @kodjomiles's task —— View job

---

PR Review in Progress

Reviewing PR #2666: "PORTN-3235 Map prs to service in a monorepo guide"

Todo List:

• Read CONTRIBUTING.md to understand review guidelines
• Read CLAUDE.md for repo-specific instructions (file not found)
• Review new guide: docs/guides/all/map-prs-to-services-in-monorepo.md
• Review changes to: src/components/guides-section/consts.js
• Check for documentation standards compliance
• Provide comprehensive review feedback

Review Results

This PR adds a comprehensive guide for mapping GitHub pull requests to services in a monorepo. Here's my detailed review:

✅ Strengths

1. Well-structured content: The guide follows a logical flow from prerequisites through implementation to testing
2. Comprehensive coverage: Covers blueprint creation, data sources, automations, and testing
3. Proper integration: Correctly added to the guides section with appropriate tags and metadata
4. Clear step-by-step instructions: Each section provides detailed, actionable steps
5. Good use of expandable sections: Complex JSON configurations are properly collapsed for readability

⚠️ Issues Found

Documentation Standards Issues

1. Header capitalization inconsistency (map-prs-to-services-in-monorepo.md:6)

   • Current: # Map PR's to services in a monorepo
   • Should be: # Map PRs to services in a monorepo
   • Per CONTRIBUTING.md: Headers should have capital letter only for first word, and "PR's" should be "PRs"

2. Inconsistent apostrophe usage

   • Title uses "PR's" but should be "PRs" (possessive not needed)
   • This affects both the markdown file and the consts.js entry

3. Missing accessibility considerations (map-prs-to-services-in-monorepo.md:86, 179)

   • Code blocks lack alt text descriptions for screen readers
   • Consider adding brief descriptions of what each JSON schema represents

4. Link format concerns (map-prs-to-services-in-monorepo.md:14, 17)

   • Links appear to use full paths correctly ✅
   • Internal links properly formatted ✅

Technical Content Issues

5. Hardcoded values (map-prs-to-services-in-monorepo.md:238, 333)

   • Line 238: repos: - platform should provide guidance on customizing this
   • Line 333: YOUR_GITHUB_TOKEN needs clearer instructions on token creation

6. Incomplete error handling (map-prs-to-services-in-monorepo.md:392)

   • The automation mapping could benefit from error handling examples
   • No troubleshooting section for common issues

7. Missing prerequisites detail (map-prs-to-services-in-monorepo.md:16)

   • "Services organized in directories with a service.yml file" needs more specificity
   • Should provide example directory structure

Code Quality Issues

8. Proper integration in consts.js ✅
   • Correctly added at line 1346-1351
   • Proper tags: ["SDLC", "GitHub", "Automations"]
   • Appropriate logos: ["GitHub"]
   • Correct link path

📝 Recommendations

1. Fix title capitalization in both markdown file and consts.js
2. Add example directory structure in prerequisites
3. Expand troubleshooting section with common issues
4. Provide clearer token setup instructions
5. Add brief descriptions for complex JSON blocks
6. Consider adding screenshots per CONTRIBUTING.md guidelines for guides

🎯 Checklist Status

Based on CONTRIBUTING.md document review checklist:

• Content is accurate and up-to-date
• ❌ Spelling and grammar need minor fixes (apostrophe usage)
• ❌ Formatting needs header capitalization fix
• Links work correctly
• Code examples follow best practices
• Tone is consistent with Port's documentation style
• Content is organized logically
• ❌ Some technical terms could use more explanation
• No marketing language present

🏁 Overall Assessment

This is a solid and valuable addition to the documentation with comprehensive coverage of a complex automation workflow. The content is technically sound and well-structured. The main issues are minor formatting inconsistencies that should be addressed before merging.

Recommendation: ✅ Approve after addressing formatting issues - particularly the title capitalization and apostrophe usage.

---