贡献者工作流程

注意

这是一份动态文档。欢迎您通过创建 问题 来提出对该工作流程的更改建议。

Fortran stdlib 贡献者工作流程

本文件描述了我们当前的工作流程。

我们欢迎任何人都来参与并提出对 stdlib 的补充建议。即使您没有规范或实现方面的经验,只要您有关于 stdlib 的想法,都可以提出。如果该想法在社区中很受欢迎,更有经验的贡献者将帮助您完成所有 5 个步骤。

  1. 想法: 您有了一个想法或提议。创建一个 问题 来讨论它。这相当于 "社区是否对在 stdlib 中添加图像读取器/写入器函数感兴趣?" 这一步的目的是了解社区是否对将该功能作为 stdlib 的一部分感兴趣。

  2. API: 当提议似乎引起了社区的极大兴趣(绝大多数参与者认为这是一个好主意)时,继续讨论具体的 API。如果您已经有了 API 的想法,可以从一开始就提出。这一步是探索性的,其目标是了解 API 应该看起来感觉如何。

  3. 规范: 讨论 API 并进行迭代。当 API 获得绝大多数人的认可时,继续进行实现并提交 PR。小 PR 总是比大 PR 更好。可以只实现新模块的几个函数,并在之后的 PR 中继续处理其他函数。所有新的功能都放在 "实验性" 命名空间中 (version: experimental)。在提交 PR 时,如果您提交新的面向公众的 API,请同时提供规范文档的初稿以及该规范的初始参考实现。该 规范是一个文档,它描述了 API 和功能,因此任何人都可以利用它从头开始创建实现,而无需查看 stdlib。然后,stdlib 库提供参考实现。

  4. 实现 (实验性): 当打开 PR 时,请从一个或多个最相关的人员那里请求审查。这些人很可能参与了工作流程的先前步骤。鼓励其他贡献者(未明确邀请)也提供审查和建议。进行迭代,直到所有(或大多数)参与者达成一致。如果对大多数可能的调用场景(有或没有可选参数,有触发错误的参数)都进行了单元测试,并且 PR 获得了绝大多数人的认可,则可以合并 PR。

  5. 发布: 从实验性版本迁移到发布版本。实验性 "命名空间" 包含新的功能及其规范。为了从实验性版本迁移到发布版本,规范文档必须获得社区和标准委员会(非正式)的批准。如果获得批准,则表示该功能已获得广泛使用,我们可以将代码迁移到 stdlib 的主部分,并且特定规范文档将成为 Fortran 标准库的一部分。

注意: 上面的 "绝大多数" 一般是指至少 80%,但最终取决于我们自己的判断,以确保社区一致认为每个 PR 和提议都获得了 "绝大多数" 的认可。

欢迎您通过创建 问题 来提出对该工作流程的更改建议。

构建系统

该项目支持两种构建系统,fpm 和 CMake。

CMake 构建文件

CMake 的构建文件允许树内构建,即构建产物与源文件位于同一目录树,也允许树外构建,即构建产物位于单独的目录树。两种构建类型都明确支持并经过测试,建议在本地开发中使用后者。

主库目标的源文件在 src/CMakeLists.txt 中相对于库目标添加,即不需要使用绝对路径。

要添加测试,应使用宏 ADDTEST 而不是 CMake 函数 add_test,该宏隐藏了可执行目标的创建,与主库目标的链接以及测试的注册。测试本身在 test 中的子目录中定义为独立的可执行文件,必须在 test/CMakeLists.txt 中注册一个新的包含测试的子目录。

源代码树应被视为只读。对 PROJECT_SOURCE_DIRCMAKE_CURRENT_SOURCE_DIR 的引用只能用于访问源文件,不能用于写入构建输出,应使用 PROJECT_BINARY_DIRCMAKE_CURRENT_BINARY_DIR 来写入构建产物。为了完全支持树内构建,构建产物绝不能与源文件同名,以避免意外覆盖它们,例如在预处理或配置文件时。

CMAKE_INSTALL_PREFIX 只能在安装时写入,不能在构建过程中写入。要安装生成的文件,在构建树中创建一个构建输出,并使用 install 函数安装它。该项目遵循 GNU 安装惯例,这意味着必须使用变量 CMAKE_INSTALL_BINDIRCMAKE_INSTALL_LIBDIRCMAKE_INSTALL_INCLUDEDIR 而不是 binlibinclude。库目标应该在安装时导出,以便在其他 CMake 项目中正确包含该项目。文件名的首选格式为使用连字符,例如 project-configproject-targets,而不是驼峰式,例如 projectConfigprojectTarget,因为前者可以通过串联 PROJECT_NAME 变量轻松构造。

该项目可以用作 CMake 子项目。必须避免对 CMAKE_SOURCE_DIRCMAKE_BINARY_DIR 的显式引用,以免破坏子项目的构建。您可以在这里 找到一个示例项目 来测试 CMake 子项目集成。