jos-reproducibility

name	jos-reproducibility
description	当你要为投向《软件学报》(Journal of Software, JOS) 的软件学科稿件建立可复现性与实验可重复保障时使用。覆盖数据/代码可用性声明、环境与依赖固定、随机性与种子控制、挖掘与大模型实验的出处锁定与输出缓存、可复现材料的目录组织与 README，以及"可根据要求提供"这类弱表述的规避，帮助你让《软件学报》(Journal of Software) 审稿人相信你的实验结果可被他人重复得到。

《软件学报》可复现性与实验可重复 (Journal of Software Reproducibility)

《软件学报》(Journal of Software, JOS) 的软件学科审稿人越来越看重结果能否被他人重复。虽然 本刊尚无公开的强制 artifact 评审轨道（现状 待核实，见 jos-artifact-evaluation），但提供可复现材料能显著增强 说服力。本技能给出让实验可重复的工程做法（来源见 resources/official-source-map.md）。

一、数据/代码可用性声明

• 在论文中明确：代码、数据、脚本是否可获取、在哪里获取、以什么许可。
• 避免弱表述："可根据要求提供 (available upon request)"在评审中是弱项而非中性占位； 尽量给出可访问链接（仓库/归档）。
• 若因隐私/版权不能公开，说明原因，并提供可复核的替代（脱敏样本、合成数据、评测协议）。

二、环境与依赖固定

• 记录操作系统、语言/编译器版本、关键库版本；提供依赖清单（requirements/pom/lockfile）。
• 优先容器化（Docker/镜像）或提供一键脚本，降低他人复现门槛。
• 说明硬件要求（CPU/GPU/内存），标注实验的资源与耗时量级。

三、随机性与可重复

• 固定随机种子；若结果对种子敏感，多次运行报告均值与方差。
• 明确数据划分方式（固定划分或交叉验证），避免每次运行结果漂移。
• 记录训练/评测的确切配置，使他人能复现同一条件。

四、挖掘与大模型实验的出处锁定

• 挖掘类：记录仓库 URL + commit SHA、抽取日期、筛选与清洗脚本、被排除比例；保存快照。
• 大模型类：记录模型标识与版本、日期、温度等参数；缓存原始模型输出，使复现不依赖 实时 API（否则是重采样而非复现）。
• 讨论数据污染并说明缓解（时间切分/私有集），与威胁有效性呼应（见 jos-experiments）。

五、可复现材料的组织

artifact/
├── README.md            # 目标、环境、一键复现步骤、预期结果、耗时
├── code/                # 源码，含入口脚本
├── data/                # 数据或获取脚本（大数据给下载脚本+校验和）
├── scripts/             # 复现各 RQ/表/图的脚本
├── results/             # 预期输出/日志样例
└── LICENSE              # 开源许可

• README 要能让第三方从零复现主要结果：列出每个表/图对应的运行命令与预期。
• 提供校验（checksum）确保数据完整；大文件用归档（Zenodo/校内镜像）+ 稳定链接。

六、复现自检清单

[ ] 论文有数据/代码可用性声明，非"可根据要求提供"
[ ] 环境与依赖版本已记录，最好容器化
[ ] 随机种子固定或多次平均报告方差
[ ] 数据划分明确，无泄漏
[ ] 挖掘类锁定 SHA 与抽取日期并保存快照
[ ] 大模型类缓存原始输出、记录模型版本与日期
[ ] 材料含 README，能从零复现主要表/图
[ ] 材料合法可分享（许可、脱敏）

七、输出格式

【可复现就绪度】强 / 中 / 弱
【可用性声明】是否给出可访问链接：________
【环境固定】依赖/容器化缺口：________
【出处锁定】挖掘 SHA / 大模型缓存：________
【材料组织】README 能否支撑从零复现：________
【下一步】用 jos-artifact-evaluation 判断是否随专刊/编辑部要求提交材料

八、常见问题

• 只放代码不放数据（或反之），无法端到端复现。
• README 缺"预期结果"，复现者无法判断是否复现成功。
• 大模型实验依赖实时调用，结果每次不同，实为重采样。
• 材料含敏感/受版权数据，无法合法分享却直接上传。

九、可重复性的三个层次

把"可重复"拆成三个层次有助于自评你的材料到了哪一步，也便于向《软件学报》(Journal of Software) 审稿人说明：

• 可重复 (repeatable)：同一团队、同一环境能再次得到相同结果。这是底线，靠固定种子、 锁定环境、脚本化实现。
• 可复现 (reproducible)：他人用你提供的材料与数据，能得到一致结果。这要求 README、环境 说明、一键脚本齐备，是本刊语境下最值得追求的层次。
• 可复制 (replicable)：他人用独立实现/独立数据，能得到一致的结论。这更强，往往由后续 工作完成，但你可通过清晰的方法描述为其铺路。

十、把可复现写进论文

• 在方法或实验节明确描述实验条件（数据、划分、超参、环境），使读者即便不看代码也能理解 如何复现。
• 用一句话给出可用性声明与链接，放在显眼位置（如脚注或"数据可用性"小节）。
• 在威胁有效性里坦陈复现的限制（如依赖特定硬件、数据规模），并说明缓解。

十一、快速对照

[ ] 达到"可复现"层次：他人用材料能得到一致结果
[ ] 论文正文描述了完整实验条件
[ ] 可用性声明位置显眼、链接稳定
[ ] 威胁有效性讨论了复现限制
[ ] 材料合法、脱敏、许可清晰

在《软件学报》(Journal of Software) 的软件学科语境下，可复现不是额外负担，而是研究质量的 一部分：能被他人重复得到的结果，天然比"只有作者本人跑得出来"的结果更可信。把可复现当作 从实验设计之初就贯穿到定稿的一条主线，而非投稿前临时补的材料，才能真正经得起审稿人的核验。

提醒：本刊是否在特定专刊要求代码/数据可用性、以及归档渠道要求，属 待核实，请以 《软件学报》(Journal of Software) 编辑部与专刊征稿页为准。工具适配见 resources/code/README.md。