How Do Developers Use Migration Guides? A Case Study of Log4j

Migration guides are a form of software documentation that helps developers address breaking changes introduced in library version updates. Prior studies have examined documents such as release notes, API reference manuals, and patch notes. However, research that focuses specifically on migration guides remains limited. Improving the usability and coverage of migration guides is essential for helping developers resolve breaking changes efficiently. Yet, we still lack a clear understanding of how migration guides are currently provided and how developers use them in practice.

To fill this gap, we first conduct a preliminary study. We use a dataset that collects real-world breaking changes. We investigate whether libraries known to introduce incompatibilities provide migration guides. We then conduct a detailed case study on Log4j, a library that has experienced large-scale breaking updates in the past. We empirically analyze how developers refer to and use the official migration guide in real-world projects.

In the Log4j case, human PR authors were the most common group to reference migration guides, accounting for 38 out of 64 PRs, and most references appeared in PR bodies. In the PRs we manually checked, migration guides were used not only for library compatibility tasks but also for other development and maintenance purposes in 30% of cases. These findings provide a foundation for improving migration guide design and for developing automated assistance tools to help developers manage breaking changes.