Why Are My Pull Request Descriptions Constantly Revised? Understanding Modifying Descriptions and Reviewer Suggestions

On GitHub, developers submit their code changes to projects through pull requests (PRs), which include descriptions to help reviewers understand the modifications and make informed review decisions. However, the PR descriptions provided by developers may sometimes be unclear. We find that a quarter of PR descriptions have undergone modifications. This process can be time-consuming for both developers and reviewers. Previous studies have focused on the automatic generation of PR descriptions, neglecting the importance of understanding the modification suggestions made by reviewers. Understanding these suggestions is crucial for improving PR descriptions, ensuring they can enable clear and effective communication, and speeding up the review process. To address this, we conduct an empirical study on 70,314 PRs with description modifications. We identify five categories and 17 types of information elements in description modification suggestions, such as “function summary”, “motivation”, and “related issue”. Surprisingly, 40% of suggestions are not adopted. We analyze the reasons why developers choose not to follow these suggestions, including reasons such as incorrect or difficult-to-implement suggestions. Through regression experiments, we find that modifying descriptions as suggested is positively correlated with a 4.31 times higher PR acceptance odds compared with those not following the suggestions. To enhance our understanding of what constitutes a high-quality PR description, we conducted an online survey to explore best practices for writing PR descriptions. These practices highlight the importance of clarity, context, and technical details in PRs, with eight of them being identified as highly significant. Based on these findings, we discuss recommendations for both developers and tool designers.