{"paper":{"title":"How Do Developers Use Migration Guides? A Case Study of Log4j","license":"http://creativecommons.org/licenses/by/4.0/","headline":"Developers most frequently reference the full migration guide in pull request descriptions and use it for maintenance tasks beyond initial updates.","cross_cats":[],"primary_cat":"cs.SE","authors_text":"Kazumasa Shimari, Kazuma Yamasaki, Kenichi Matsumoto, Takahiro Monno, Tetsuya Kanda","submitted_at":"2026-04-27T05:59:28Z","abstract_excerpt":"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.\n  To fill this gap"},"claims":{"count":4,"items":[{"kind":"strongest_claim","text":"Pull request authors most frequently reference the migration guide in the pull request description, and that most references (82.81%) link to the entire guide rather than specific sections. Developers use migration guides not only during major version updates but also during subsequent maintenance tasks.","source":"verdict.strongest_claim","status":"machine_extracted","claim_id":"C1","attestation":"unclaimed"},{"kind":"weakest_assumption","text":"That the presence of a reference to the migration guide in a pull request description reliably indicates that the developer actually read and followed the guide, and that the sampled Log4j projects and PRs generalize to other libraries and developer populations.","source":"verdict.weakest_assumption","status":"machine_extracted","claim_id":"C2","attestation":"unclaimed"},{"kind":"one_line_summary","text":"Developers reference the full Log4j migration guide in 82.81% of pull request descriptions and use it for both major updates and subsequent maintenance tasks.","source":"verdict.one_line_summary","status":"machine_extracted","claim_id":"C3","attestation":"unclaimed"},{"kind":"headline","text":"Developers most frequently reference the full migration guide in pull request descriptions and use it for maintenance tasks beyond initial updates.","source":"verdict.pith_extraction.headline","status":"machine_extracted","claim_id":"C4","attestation":"unclaimed"}],"snapshot_sha256":"c14eb4dab8fcea0650e0e8d1750a424af1c5172798f1fe09a7099a84e3f13b38"},"source":{"id":"2604.24072","kind":"arxiv","version":2},"verdict":{"id":"bfa129d1-4590-44d0-8f33-ec465fdf2497","model_set":{"reader":"grok-4.3"},"created_at":"2026-05-08T03:25:50.130584Z","strongest_claim":"Pull request authors most frequently reference the migration guide in the pull request description, and that most references (82.81%) link to the entire guide rather than specific sections. Developers use migration guides not only during major version updates but also during subsequent maintenance tasks.","one_line_summary":"Developers reference the full Log4j migration guide in 82.81% of pull request descriptions and use it for both major updates and subsequent maintenance tasks.","pipeline_version":"pith-pipeline@v0.9.0","weakest_assumption":"That the presence of a reference to the migration guide in a pull request description reliably indicates that the developer actually read and followed the guide, and that the sampled Log4j projects and PRs generalize to other libraries and developer populations.","pith_extraction_headline":"Developers most frequently reference the full migration guide in pull request descriptions and use it for maintenance tasks beyond initial updates."},"integrity":{"clean":true,"summary":{"advisory":0,"critical":0,"by_detector":{},"informational":0},"endpoint":"/pith/2604.24072/integrity.json","findings":[],"available":true,"detectors_run":[{"name":"doi_compliance","ran_at":"2026-05-19T22:25:52.724153Z","status":"completed","version":"1.0.0","findings_count":0}],"snapshot_sha256":"089dafd10ff3113a7abfe83cb2532ea7cda8d771818c1f24d71ceba5f93ce11d"},"references":{"count":0,"sample":[],"resolved_work":0,"snapshot_sha256":"258153158e38e3291e3d48162225fcdb2d5a3ed65a07baac614ab91432fd4f57","internal_anchors":0},"formal_canon":{"evidence_count":0,"snapshot_sha256":"258153158e38e3291e3d48162225fcdb2d5a3ed65a07baac614ab91432fd4f57"},"author_claims":{"count":0,"strong_count":0,"snapshot_sha256":"258153158e38e3291e3d48162225fcdb2d5a3ed65a07baac614ab91432fd4f57"},"builder_version":"pith-number-builder-2026-05-17-v1"}