笔记本开发工作流程

笔记本开发工作流程#

本文档描述了JWST数据分析工具（JDAT）对“笔记本驱动开发”的方法。这里的程序概述了将笔记本通过连续开发阶段的过程，以便成为可以在spacetelescope笔记本库中“实时”使用的内容。

这些笔记本可以有许多不同的科学案例，但遵循相对标准的工作流程：

  1. 草稿阶段

  2. 基线阶段

  3. 笔记本驱动开发

  4. 高级阶段

  5. 基于社区反馈的修订

这些阶段及其之间的转换过程将在下面描述。

通过拉取请求提交笔记本的程序在本文件的 GitHub部分 中进行了描述。这一过程在每个阶段都重复。

请注意，关于编写Jupyter笔记本的信息可以在 STScI笔记本风格指南 中找到，关于Python代码的类似指导可以在 STScI Python风格指南 中找到。这些指南旨在简化审查步骤。

Important

请注意，所有与JDAT相关的代码应使用`Python 3`编写；`Python 2`不受支持。

草稿阶段#

此阶段的主要目的是记录科学工作流程，但不包括实际代码。此阶段通常主要由科学家完成。如果笔记本较简单或基础工具已经足够成熟，可以直接实现，则可以合理地跳过此阶段。

在此阶段开始笔记本时，笔记本作者应从`笔记本风格指南 <spacetelescope/style-guides>`_ 的笔记本模板或空白Jupyter笔记本开始。然后，他们用文字写出他们的工作流程。在可能的情况下，他们提供*示例*代码，即使它尚未实现。

例如，作者可能会在这样的笔记本中写道：

In [ ]: spectral_line = find_line(jwst_miri_spectrum)

# `spectral_line` 应该是一个按spaxel索引的线中心和线名称的列表，
# 使用基于导数的线查找器找到。

即使``find_line``函数尚不存在。

笔记本的顶级标题（即标题）应以“草稿：”开头，以明确这是一个草稿笔记本。然而，文件名不应包含`draft`，因为文件名在后续阶段通常保持不变。

一旦草稿准备好，作者应创建一个拉取请求，包含草稿笔记本的内容（请参见本文末尾的说明）。

基线阶段#

此阶段的主要目的是获得一个功能性笔记本，以记录工作流程。此阶段通常也由科学家完成（尽管可以向开发人员询问问题）。这通常是开发的*第一*步。也就是说，如果工作流程已经合理地可以用现有工具实现，则不需要草稿笔记本。

在此阶段，笔记本应实际从头到尾执行，但可以“粗糙”。例如，笔记本可能有几个单元格，其中包含如下内容：

In [ ]: spec = Spectrum(np.linspace(a, b, 1000)*u.angstrom, some_complex_function(...))

科学家可能认为这太复杂，因此为了传达他们对改进工作流程的期望，他们创建一个“开发者注释”。开发者注释应作为笔记本的一部分，并应为一个单独的markdown单元格（而不是代码单元格 - 开发者注释中的代码示例可以作为文字markdown块完成 - 即用` ````包围块或用` `表示内联代码）。该单元格应以文本``*开发者注释:*``开头。例如，可以在笔记本中添加如下的markdown单元格：

*开发者注释:*
创建上述光谱有点复杂，如果有一个简单的函数可以直接执行 `spec = simulate_jwst_spectrum(a, b)`，将会改善工作流程。

从而提供指导，说明特定开发将如何简化工作流程。

如果以这种形式新创建了笔记本，作者可以按照“通过拉取请求提交笔记本的程序”（见本文末尾）跳过草稿阶段步骤。

如果笔记本是在草稿阶段步骤中已创建，并且已经遵循了“通过拉取请求提交笔记本的程序”，则作者只需创建一个新分支以修改现有代码，然后在准备好后创建一个新的拉取请求。

在任何情况下，笔记本的标题（但不是文件名）应以“基线:”开头，以指示笔记本处于基线阶段。

一旦创建了拉取请求，笔记本将自动在库中构建，以便审阅者可以查看。审阅者可以在GitHub上对笔记本进行评论。在此阶段，审查的标准仍然相对较低 - 主要是确保笔记本从头到尾运行，并且数据文件等没有意外提交到库中。

最后，有三个重要的技术细节与笔记本在此阶段相关（并在未来阶段继续适用）：

  1. 在进行git提交之前，笔记本的输出单元格应*始终*被清除。笔记本输出有时可能非常大（例如图表等），而git旨在处理源代码，而不是数据。清除输出还确保笔记本可以从头到尾运行，因此可以被他人重现。

  2. 笔记本所需的任何数据文件需要其他可能审查或测试笔记本的人可以访问。应遵循`STScI关于笔记本数据存储的指南 <spacetelescope/style-guides>`_。JWST笔记本的具体补充是，笔记本数据应位于``DMD_Managed_Data/JWST/jwst-data_analysis_tools`` Box文件夹（或其子文件夹）中。如果您尚未访问此Box文件夹，请向项目科学家询问，他们应该能够为您添加访问权限。请注意，如果基线笔记本使用的数据尚不应公开，最简单的选择可能是中央存储，但在这种情况下，笔记本状态必须明确指出它必须在STScI网络内运行。

  3. 笔记本应清楚地说明生成笔记本所使用的各种依赖项的版本。这些版本应放在与笔记本本身位于同一目录中的``requirements``文件中。该文件的示例位于``example_notebook``文件夹中。这将确保审阅者/测试者可以确认，如果他们遇到问题，问题不是由于软件版本不匹配造成的。

笔记本将经历科学和技术审查，这也可能产生额外的开发者注释。解决审查意见后，它将被合并到库中。这标志着基线阶段的结束。

笔记本驱动开发#

在草稿和基线阶段及之后，可能需要进行大量开发。基线笔记本可能包含许多希望在数据分析工具中进行更多开发的领域，或者可能只需要一些小的调整（或根本不需要！）。因此，此阶段是最灵活的，依赖于开发资源等。一般来说，开发人员的意图是能够重用笔记本中的代码片段作为开发测试，同时偶尔（如有必要）向笔记本作者寻求指导，以确保实现确实满足笔记本的需求。此步骤没有正式的流程，但JDAT规划过程（目前在Jira上）旨在跟踪在给定笔记本可以进入下一个阶段之前所需的具体步骤。

高级阶段#

一旦基线笔记本完成，下一阶段是将基线构建为尽可能一致地使用DAT或相关社区开发的软件的笔记本。这通常通过开发人员审查基线笔记本并与科学家合作开发额外的DAT代码来完成，特别关注解决“开发者注释”。笔记本作者和开发人员共同决定谁实际修改笔记本并发起拉取请求，但很可能两者都会在某种程度上参与。一个示例方法是，开发人员从基线笔记本开始，标记出如下评论（使用上述示例）：

In [ ]: spec = Spectrum(np.linspace(a, b, 1000)*u.angstrom, some_complex_function(...))

创建上述光谱有点复杂，如果有一个简单的函数可以直接执行 spec = simulate_jwst_spectrum(a, b)，将会改善工作流程。

*开发进展:*
这现在已实现为JWSTSimulator.make_spectrum(a, b, anotherparameterthatturnsouttobeimportant)。你能试试这个并确保它在这里有效吗？

然后创建一个包含这些评论的git提交。原作者随后将在后续提交中解决这些评论。随着笔记本驱动开发的继续，可能会有多个此类拉取请求。但一旦所有开发者注释都得到解决，开发人员和作者可以宣布笔记本准备好称为“高级”。

一旦笔记本作者（原作者和开发人员/审阅者）达成一致认为它已准备好，其中一人按照上述拉取请求工作流程进行操作，但笔记本标题现在仅更改为标题本身（没有“草稿:”或“基线:”）。然后，拉取请求将由项目科学家之一进行审查，并在所有人对笔记本满意时合并。

基于社区反馈的修订#

当然，科学并不是静止不变的！随着时间的推移，一些已完成的笔记本可能需要增强或更改。一般来说，这些遵循标准的拉取请求工作流程，并且一旦笔记本公开（在STScI内外），任何人都可以提交。虽然库维护者管理此过程，但笔记本作者可能会不时被召集以提供对任何提议更改的意见或看法。

Contents