In the pull-based development model, code contributions are submitted as pull requests (PRs) to undergo reviews and approval by other developers with the goal of being merged into the code base. A PR can be supported by a description, whose role has not yet been systematically investigated. To fill in this gap, we conducted a mixed-methods empirical study of PR descriptions. We conducted a grey literature review of guidelines on writing PR descriptions and derived a taxonomy of eight recommended elements. Using this taxonomy, we analyzed 80K GitHub PRs across 156 projects and five programming languages to assess associations between these elements and code review outcomes (e.g., merge decision, latency, first response time, review comments, and review iteration cycles). To complement these results, we surveyed 64 developers about the perceived importance of each element. Finally, we analyzed which submission-time factors predict whether PRs include a description and which elements they contain. We found that developers view PR descriptions as important, but their elements matter differently: purpose and code explanations are valued by developers for preserving the rationale and history of changes, while stating the desired feedback type best predicts change acceptance and reviewer engagement. PR descriptions are also more common in mature projects and complex changes, suggesting they are written when most useful rather than as a formality.

翻译：在基于Pull的开发模型中，代码贡献以Pull Request（PR）的形式提交，由其他开发者进行审查和批准，以期被合并到代码库中。PR可以附带描述，但其作用尚未得到系统研究。为填补这一空白，我们对PR描述进行了混合方法的实证研究。我们首先对撰写PR描述的指南进行了灰色文献综述，并推导出八项推荐要素的分类法。利用该分类法，我们分析了来自156个项目、涵盖五种编程语言的80K个GitHub PR，以评估这些要素与代码审查结果（如合并决策、延迟时间、首次响应时间、审查评论和审查迭代周期）之间的关联。为补充这些结果，我们调查了64名开发者对每个要素重要性的认知。最后，我们分析了哪些提交时因素能预测PR是否包含描述及其包含的要素。研究发现，开发者认为PR描述很重要，但其要素的重要性存在差异：目的和代码解释因能保留变更理由和历史而受到开发者重视，而说明期望的反馈类型最能预测变更接受度和审查者参与度。PR描述在成熟项目和复杂变更中更为常见，这表明其撰写是基于实际效用而非形式要求。