Skip to main content
Version: Latest(3.11)

NASL 提案流程（NASL RFCs process）

caution

提案流程目前只对内开放。

提案流程（request for comments process），旨在为 NASL 引入新特性或变更时提供一致且可控的路径。

哪些情况需要遵循此流程？​

如果您想对 NASL 的以下方面进行更改、创新或删除时，需要遵循此流程：

  • NASL 的语法树
  • NASL 的语义（提供框架的声明）
  • NASL 的标准库 API（包括内置数据结构、内置函数、内置逻辑）
  • NASL 的文本语法

为什么需要这样做？​

很高兴您正在考虑对 NASL 提出新功能或更改建议——我们感谢您的贡献！目前有很多岗位的同学直接或间接参与到 NASL 和相关库的设计和实现中，随着低代码产品由快速增长转向完善体验的阶段，我们需要更加重视稳定性，因此必须仔细考虑我们所做的每一个变更到中间的开发实施成本和对最终用户的影响。

整体流程​

flowchart LR 提案人([提案人]) -- 思考和设计提案 --> 涉及AST变更{涉及AST变更} 涉及AST变更 -- yes --> MR -- 评委合MR --> 对应feature分支 -- 生成 --> 前端AST 涉及AST变更 -- no --> Issue 对应feature分支 -- 生成 --> 后端AST 对应feature分支 -- 生成 --> NASL文档 对应feature分支 -- 生成 --> JSONSchema[JSON Schema] MR -- pipeline-check\nTS定义语法和NASL设计规范 --> MR Issue -- 评审和讨论 --> Issue

如何提案？​

如果要对上文中提到的 NASL 几个方面进行更改、创新或删除时，需要进行提案。

⭐️目前 NASL AST 统一采用defs目录下的 TypeScript（限制版）来定义语法树。

如果涉及到 NASL 语法树变更，统一基于 MR 进行提案，将提案内容填写在 GitLab 的 MR 描述中（注意不是 md 文件！），其它统一基于 issue 提案。详细流程见下方说明。

不管使用何种方式均都需要根据此仓库中的.gitlab/issue_templates/feature_request.md模板来编写您的提案

  • 最重要的是清晰直观，重点描述变更项和具体含义，其他直接链接对应的 specification；
  • 有需求和技术评审文档需要提供链接；
  • 事先可以线下沟通，优化提案质量。

基于 issue 的提案流程（不涉及 AST 变更，在线编辑）​

  • 点击左侧Issues右侧点击New issue创建 issue
  • 填写标题并在 Description 栏选择feature_request作为模版
  • 填写提案内容并在Labels中选择合适的标签
    • 根据提案状态（择一）：草稿态、待评审、评审通过待开发、已落地、...
    • 根据提案内容（可多选）：标准库、语义、语法树、术语、...
  • 点击左下角Create issue

基于 MR 的提案流程（涉及 AST 变更，代码+在线编辑）​

  • 前置安装 Node.js 16-18
  • clone 这个仓库
  • checkout 分支 feature/some-rfc
  • 修改 defs 目录下的 TypeScript 文件
  • 可以手动 run check 做检查
npm run check
  • 然后在 GitLab 上创建 MR
  • 填写标题并在 Description 栏选择feature_request作为模版
  • 填写提案内容并在Labels中选择合适的标签
    • 根据提案状态（择一）：草稿态、待评审、评审通过待开发、已落地、...
    • 根据提案内容（可多选）：标准库、语义、语法树、术语、...
  • 点击左下角Create Merge Request
  • CI 会做检查

最终，NASL 技术委员会将决定该提案是否会引入 NASL 中。

如何评审？​

周期会议​

制定 NASL 评审周期会议，每周二下午 14:00 - 18:00，有提案就评审，没有提案就放空。

会在前一天提前发出来需要评审的提案。

线下评审​

统一采取线下拉会评审，提案人可以在周二参与集中评审，也可以在紧急时日常主动发起会议。

评委要求​

NASL 技术委员会包含以下成员（按拼音排序）：何少甫、庞概、汪韬、吴登轲、杨剑飞、张炜昕、赵清江、赵雨森、朱子润

极端情况下是 4 位评委，常规情况建议 >=6 位

通过后如何实施？​

合并 MR​

  • 在评审通过后，提案人提交新的 commit，将其他方案删除，只保留最终方案（其他方案可以在 commit history 中查看）
  • 在需求提测后，评委再将 MR 分支合并到 test 分支
  • 生成前后端 sdk 的方案待定...（可能也可以直接走流水线）

灵感来源​

其他​

NASL 提案流程与日常产品的其他流程不冲突。NASL 提案流程和 NASL 技术委员会只关注 NASL 变更时是否一致和可控。

NASL 提案流程可以有多种输入，比如产品日常需求涉及 NASL 语义变更、开发人员提案、产品新提案等。NASL 提案流程也可以有对外输出，比如技术主动发起的 NASL 提案，影响到产品调整，这时反馈到产品进行提案。