A pull request description policy defines the minimum context a proposed API change must provide before reviewers begin design review. It can require a work-ticket reference, such as DEV-1234, and an explanation of why the change is needed. section 8.2 section 8.8
The policy supports reviewers who cannot consult the submitter directly. A work-ticket link helps only when the ticket contains useful background; otherwise, reviewers still have to search for context or infer it. section 8.8
Implement the policy with complementary controls:
- Use a Markdown pull request template as a short checklist for required context. section 8.8
- Validate title and description content automatically where the hosting system or pipeline supports it. section 8.2 section 8.8
- Keep human governance approval separate from automated checks; passing the policy does not replace design review. section 8.2
A minimum API proposal policy
Require the pull request title to contain a Jira reference matching DEV-XXXX and require the description to explain why the API change is necessary. Use the template to prompt these fields, then require the automated checks and governance approval before merging. section 8.2 section 8.8
#!/bin/bash
commit_msg_file=$1
# Read the commit message file
commit_msg=$(cat "$commit_msg_file")
# Pattern to match Jira issue reference (DEV-XXXX)
Pattern="DEV-[0-9]{4}"
# Check if the commit message contains the Jira issue reference
if [[ ! $commit_msg =~ $pattern ]]; then
echo "Error: Commit message does not contain a valid
Jira issue reference in the format DEV-XXXX."
echo "Please include a Jira issue reference in your commit message."
exit 1
fi
Compare pull-request requirements with commit-level enforcement: the supplied shell check rejects a commit message that lacks a DEV-XXXX Jira reference. section 8.8
