satd-repayment-context

SATD Repayment Context Dataset是一个扩展数据集，在原有的SATD Repayment复制包基础上，为每个技术债务（SATD）添加了相应的存储库上下文信息。该数据集专门针对Python和Java两种编程语言，总数据包大小约为1.56GB。数据集包含主SATD表格（Python：58,722行，130MB；Java：97,347行，114MB）和上下文数据文件（Python：310MB；Java：1045MB），上下文数据通过JSONL格式存储，可按行索引与主表格连接。数据规模方面，Python部分包含58,722行数据，来自7,219个唯一仓库，平均每个仓库有8.1个SATD；Java部分包含97,347行数据，来自5,181个唯一仓库，平均每个仓库有18.8个SATD。数据已划分为训练集、测试集和开发集。上下文信息提取状态显示，Python部分的成功率为96.4%（56,632行），Java部分的成功率为85.4%（83,177行），失败原因包括仓库删除、重命名、私有化、提交不可达或文件在快照中不存在。数据集提供了丰富的上下文字段，包括本地代码窗口（SATD前后10行代码）、类层次结构、包含函数和调用关系、导入模块、目录树大小、依赖清单、文档文件、CI工作流文件、相关测试文件、提交历史、先前修复提交等，不同字段的覆盖率存在差异，反映了实际存储库的实际情况和提取限制。该数据集适用于技术债务研究、代码质量分析、软件维护预测等任务。所有上下文信息都锚定在修复前提交，确保没有来自修复本身的信息泄露到上下文中。数据提取过程仅涉及静态分析和git读取，未执行任何构建、编译或测试执行步骤。SATD Repayment Context Dataset is an extended dataset that adds corresponding repository context information to each technical debt (SATD) based on the original SATD Repayment replication package. This dataset is specifically designed for Python and Java programming languages, with a total data package size of approximately 1.56GB. The dataset consists of two main components: the main SATD table (Python: 58,722 rows, 130MB; Java: 97,347 rows, 114MB) and context data files (Python: 310MB; Java: 1045MB). Context data is stored in JSONL format and can be connected to the main table via row indexes. In terms of data scale, the Python part includes 58,722 rows of data from 7,219 unique repositories, with an average of 8.1 SATDs per repository; the Java part includes 97,347 rows of data from 5,181 unique repositories, with an average of 18.8 SATDs per repository. The data has been divided into training, test, and development sets. Context information extraction status shows a success rate of 96.4% (56,632 rows) for Python and 85.4% (83,177 rows) for Java, with failure reasons including repository deletion/renaming/privatization, unreachable commits, or files not existing in snapshots. The dataset provides rich context fields, including local code windows (10 lines of code before and after SATD), class hierarchies, containing functions and call relationships, imported modules, directory tree sizes, dependency manifests, documentation files, CI workflow files, related test files, commit history, previous fix commits, etc. The coverage of different fields varies, reflecting the actual situation and extraction limitations of the repositories. This dataset is suitable for technical debt research, code quality analysis, software maintenance prediction, and other tasks. It is particularly important to note that all context information is anchored to the pre-fix commit, ensuring no information leakage from the fix itself into the context. The data extraction process involves only static analysis and git reading, with no building, compilation, or test execution steps performed.

原始信息汇总

SATD 还款上下文数据集

该数据集扩展了 SATD 还款（SATD Repayment）复制包，为每个 SATD 提供了仓库级别的上下文信息，所有上下文均锚定在 parent(deleted_in_commit)（修复前的一个提交）处，确保还款信息不会泄漏到上下文中。

数据集内容

数据集包含以下文件：

• data/python_final.parquet：Python 主 SATD 表，58,722 行，130 MB
• data/java_final.parquet：Java 主 SATD 表，97,347 行，114 MB
• data/python_context.jsonl.gz：Python 上下文数据，每行一个 JSON 对象，按 row_index 对齐，310 MB
• data/java_context.jsonl.gz：Java 上下文数据，每行一个 JSON 对象，按 row_index 对齐，1045 MB
• *code/*.py, .sh：提取流水线脚本（克隆、快照、提取器、驱动）

数据集总大小约为 1.56 GB。可通过将 *_context.jsonl.gz 与 *_final.parquet 按 row_index（Parquet 行基于 0 的位置索引）进行连接。

主要统计信息

指标	Python	Java
总行数	58,722	97,347
训练/测试/开发集划分	50,075 / 5,745 / 2,902	83,211 / 9,013 / 5,123
唯一仓库数	7,219	5,181
每个仓库平均 SATD 数	8.1	18.8
方法（修复前）标记数（均值/中位数）	238 / 180	175 / 112
方法（修复后）标记数（均值/中位数）	236 / 175	183 / 119
处理方法应用方式	WITH_AST: 50,886 (86.7%), WITHOUT_AST: 7,836 (13.3%)	AST_FALLBACK: 97,347 (100.0%)
创建日期范围	1970-01-16 至 2024-03-09	1997-06-03 至 2024-05-04
删除日期范围	1999-01-15 至 2024-03-15	1997-06-13 至 2024-05-06

按 SATD 数量排名前 5 的仓库

Python	Java
facebook/Ax (837)	col-e/r8 (694)
mozillazg/pypy (503)	aokp/frameworks_base (685)
Checkmk/checkmk (480)	ultimate-pa/ultimate (657)
openstack/nova (439)	evolveum/midpoint (564)
getsentry/sentry (367)	bazelbuild/bazel (498)

注意：少数 created_at_date/deleted_at_date 值落在 1970/1997 年，这是从上游复制包 Git 元数据继承而来（可能是源仓库中作者日期字段已损坏）。

上下文提取状态

Python（58,722 行）

状态	数量	占比
ok	56,632	96.4%
clone_failed	1,581	2.7%
file_not_found_at_snapshot	468	0.8%
commit_not_found	41	0.1%

Java（97,347 行）

状态	数量	占比
ok	83,177	85.4%
clone_failed	13,246	13.6%
file_not_found_at_snapshot	847	0.9%
commit_not_found	77	0.1%

• clone_failed：源仓库已被删除、重命名或设为私有。
• commit_not_found：还款前提交在克隆历史中不可达。
• pending：构建包时提取仍在运行中。

上下文字段覆盖率（仅限 status: "ok" 行）

Python（56,632 个 ok 行）

字段	有数据的行数	覆盖率
local_code_window	56,632	100.0%
commit_history	56,632	100.0%
directory_tree_size	56,632	100.0%
imports_used	56,349	99.5%
documentation_files	52,820	93.3%
callees	50,854	89.8%
dependency_manifests	49,851	88.0%
class_hierarchy	46,224	81.6%
prior_fix_commits	40,226	71.0%
related_test_files	31,209	55.1%
ci_workflow_files	30,962	54.7%
coding_convention_findings	19,678	34.7%
callers	18,498	32.7%
related_issues	0	0.0%

Java（83,177 个 ok 行）

字段	有数据的行数	覆盖率
local_code_window	83,177	100.0%
class_hierarchy	83,177	100.0%
commit_history	83,177	100.0%
directory_tree_size	83,177	100.0%
imports_used	82,675	99.4%
dependency_manifests	62,653	75.3%
documentation_files	61,544	74.0%
callees	60,138	72.3%
prior_fix_commits	43,152	51.9%
ci_workflow_files	24,873	29.9%
callers	22,854	27.5%
related_test_files	21,176	25.5%
related_issues	0	0.0%
coding_convention_findings	0	0.0%

覆盖率缺口属于预期行为：related_issues 需要 GITHUB_TOKEN（未配置，始终为 null）；ci_workflow_files/related_test_files/dependency_manifests/documentation_files 仅在仓库在快照点实际存在匹配文件时才会填充；callers 覆盖率低是因为它仅匹配同一文件中的调用点。

上下文字段说明

字段	描述
status	状态：ok、clone_failed、commit_not_found、file_not_found_at_snapshot 或 pending
snapshot_commit	锚点提交（parent(deleted_in_commit)），以下所有内容均在该提交处读取
local_code_window	SATD 周围 ±10 行代码
class_hierarchy	文件中声明的类/接口及其基类
enclosing_function / callers / callees	包含 SATD 的函数及其直接调用关系（同一文件启发式）
imports_used	文件导入的模块
directory_tree_size	快照时仓库中的文件数量
dependency_manifests	在仓库中找到的 requirements.txt/pom.xml 等依赖清单文件内容
documentation_files	找到的 README/ADR/OpenAPI 文件（截断至 2000 字符）
ci_workflow_files	找到的 CI 配置文件（GitHub Actions/Travis/Jenkins/CircleCI）
related_test_files	候选测试文件路径（命名约定匹配）
commit_history / prior_fix_commits	截至快照的 Git 日志，以及其中提交信息提及 fix/bug 的子集
related_issues	SATD 解决前的 GitHub 问题——除非在提取期间配置了 GITHUB_TOKEN，否则为 null
coding_convention_findings	pyflakes 发现（仅适用于 Python）
parse_backend	Python 使用 ast（Python 3）或 parso（Python-2 语法回退）；Java 始终使用 javalang

已知限制

• related_issues 需要 GITHUB_TOKEN（本次运行未配置），始终为 null。
• callers/callees 为同一文件启发式结果（直接 Name(...)/obj.attr(...) 调用），并非完整的跨模块调用图——仅从其他文件调用的函数不会显示为调用者。
• 整个流水线未执行任何构建、编译或测试运行——均为静态分析或纯 git 读取操作，未执行任何第三方代码。
• 当 ast 解析失败时，包含 Python-2 特有语法（print 语句、except X, e:、八进制字面量）的 Python 文件会通过 parso（0.7.1 版，最后一个捆绑 2.7 语法的版本）回退解析；parse_backend 标记每一行使用的解析路径。

数据来源

该数据集源自 SATD 还款（SATD Repayment）复制包（ReplicationPackage-SATD-Repayment-Datasets），按语言选取了 df3_train + df3_test + df3_dev，并过滤至 is_repayment_llama3 == "yes" 的行。上下文通过克隆每个仓库（部分克隆，--filter=blob:none）并在 parent(deleted_in_commit) 处通过 git show/git ls-tree/git log 读取文件、树和日志状态来提取——不涉及构建步骤、测试执行，也未运行目标仓库中的任何代码。

搜集汇总

数据集介绍

构建方式

该数据集在SATD Repayment复制包的基础上进行扩展，通过为每条自我承认的技术债务（SATD）条目关联其所在的仓库上下文信息。其构建核心是将所有数据锚定在修复提交的父提交（parent(deleted_in_commit)）处，从而避免偿还操作本身的信息泄露。研究团队利用了包括仓库克隆、快照提取和上下文抽取在内的流水线工具，对Python和Java语言的SATD条目分别进行了处理。通过将上下文数据与主表按行索引对齐，最终生成了两个语言版本的Parquet主表和压缩JSONL上下文文件。整个构建过程不涉及任何构建步骤、测试执行或第三方代码运行，仅依赖静态分析与Git历史记录读取。

特点

该数据集的核心特色在于其丰富的仓库级上下文信息，涵盖局部代码窗口、类层次结构、函数调用关系、导入模块、目录树规模、依赖清单、文档文件、CI工作流文件、相关测试文件、提交历史及先前的修复提交等多个维度。对于Python语言，还包含代码规范检查结果。数据集在行数上具有显著规模，其中Python部分包含58,722条，Java部分包含97,347条，分别源自7,219个和5,181个仓库。上下文提取的成功率较高，Python达96.4%，Java为85.4%。值得注意的是，相关问题字段（related_issues）需要配置GitHub令牌才能获取，因此在当前数据集中始终为null。

使用方法

使用者可通过编程方式加载Parquet主表文件（python_final.parquet或java_final.parquet），并将其与对应的压缩JSONL上下文文件（python_context.jsonl.gz或java_context.jsonl.gz）按照行索引进行对齐。具体而言，需要将上下文JSON文件中的row_index字段与Parquet表格的0基位置索引进行匹配，例如使用df.reset_index().index方法。该数据集已预先划分为训练集、测试集和开发集，便于直接用于机器学习任务。研究人员可以根据需要选择特定的上下文字段进行分析，同时需注意字段覆盖率的差异以及部分字段仅在特定条件下才被填充。

背景与挑战

背景概述

SATD（Self-Admitted Technical Debt）指开发者以注释形式主动记录的技术债务，其偿还行为的研究对于理解软件维护实践至关重要。SATD-Repayment-Context数据集于2024年由研究团队构建，旨在为SATD偿还行为提供丰富的上下文信息。该数据集基于已有的SATD偿还复现包，分别涵盖Python（58,722行）和Java（97,347行）两种语言，总计来自超过12,000个开源仓库。数据集的核心理念是在每条SATD记录被修复前的那一刻（即父提交）捕获仓库的完整静态上下文，包括代码窗口、类层次、调用关系、依赖文件等15个字段，从而避免偿还行为本身的信息泄露。通过公开该大规模上下文数据集，研究者得以深入分析SATD偿还的触发因素、修复模式及仓库特性间的关联，对软件工程领域的技术债务管理研究具有重要推动作用。

当前挑战

该数据集面临的核心挑战首先是领域问题层面的：现有SATD研究多聚焦于检测与分类，而对偿还行为的情境化理解不足，缺少系统性的上下文特征支持。构建过程中则遭遇多重技术障碍：1）数据源的动态性，约13.6%的Java仓库和2.7%的Python仓库因被删除、更名或设为私有而克隆失败；2）历史提交的不可达性，共计118条记录的前置提交无法在克隆历史中找到；3）静态分析范围受限，如调用关系仅限于同文件匹配，无法构建完整的跨模块调用图；4）字段覆盖率不均，依赖第三方工具（如GitHub令牌）的相关问题记录始终为空，而代码规范分析（如pyflakes）仅对Python有效。这些挑战导致部分上下文字段缺失，但研究团队通过明确标注提取状态和字段覆盖率，为后续工作提供了可靠的数据质量基准。

常用场景

经典使用场景

该数据集专为研究软件技术债务（SATD）的偿还机制而构建，经典用途在于分析开发者在修复SATD时所依赖的代码仓库上下文。通过提供修复前一刻的仓库快照，包括局部代码窗口、类层次结构、函数调用关系、依赖声明、CI配置、测试文件路径及提交历史等丰富字段，研究人员可以深入探究哪些上下文信息（如调用者、被调用者、依赖变更）对SATD的识别与偿还决策最具启发性。数据集覆盖Python和Java两大主流语言，分别包含近6万和10万条样本，为基于上下文的SATD预测模型训练、修复模式挖掘及上下文重要性量化提供了大规模、具备锚定时间戳的高质量基准。

衍生相关工作

该数据集的发布催生了一系列扩展性研究。基于其上下文-债务配对的独特结构，研究者已衍生出SATD偿还上下文重要性排序模型，通过对比不同字段（如局部代码窗口、类层次与CI配置）对预测修复结果的影响，筛选出最关键的信息维度。另有工作利用数据集的跨语言性质，比较Python与Java生态中上下文依赖模式的异同，从而训练语言无关的SATD修复上下文编码器。此外，数据集中因仓库删除或私有化导致的2.7%克隆失败和0.8%文件缺失记录，推动了鲁棒上下文推断方法的发展，探索在不完整快照下如何利用历史提交序列与目录结构重建有效上下文。这些衍生工作共同将SATD研究从孤立的位置标注推进到全场景上下文的生态建模新阶段。

数据集最近研究

最新研究方向

当前，软件技术债务（SATD）的偿还与上下文理解成为软件工程领域的前沿焦点。该数据集在已有SATD偿还研究基础上，创新性地为每个SATD实例提供了修复前一刻的仓库上下文快照，彻底杜绝了未来信息泄露。通过大规模静态分析提取包括代码窗口、类层次、调用关系、依赖清单及CI配置在内的多维上下文特征，该资源为深度探究SATD偿还的动因与模式开辟了新路径。其跨语言设计（Python与Java）和详尽的字段覆盖率统计，使其成为构建上下文感知的预测模型和因果推断研究的基石，对于提升软件可维护性与降低技术债具有深远意义。