基于 Github 平台的 .NET 开源项目模板 - 项目及半自动脚本
接上一篇模板的介绍文章, 我们接下来看看如何配置和使用这款模板.
项目配置
-
1. fork 咱这款模板.
-
2. 并将其设置为模板.
-
3. 在创建新仓库时使用这个模板.
-
4. 看使用说明,了解项目结构
-
5. 配置打包信息
管道配置
管道授权
管道得以正常运行需要您的授权才可,所以请您花一点时间学习如何拿到授权.
| 配置项 | 配置需求及链接 | 仓库配置项及路径 | 安全变量 KEY | 安全变量 VALUE |
|---|---|---|---|---|
| 管道授权 Token | 私人Classic Token | Setting -> Secrets and variables -> Action 创建安全变量 | REPO_GITHUB_TOKEN | {{your_classic_token}} |
| 覆盖率网站 Token | 网站完成注册, 在 codecov 中找到你的仓库 | Setting -> Secrets and variables -> Action 创建安全变量 | COVERAGE_KEY | {{your_codecov_token}} |
| NUGET网站 Token | 网站完成注册, 创建SecretKey | Setting -> Secrets and variables -> Action 创建安全变量 | NUGET_KEY | {{your_nuget_token}} |
配置文件夹及文件介绍
-
scanner.bat/sh ,针对 win/linux 编写的两个脚本, 主要是调用 Workflow.Initialization 工程项目来完成项目的扫描和配置更改, 因为它需要在扫描和生效时进行调用,鉴于这种手动行为, 姑且称其为半自动化脚本.
-
.github/project.yml,该文件为自动化脚本扫描或生成的文件, 用户更改此文件中的实体节点,重新运行脚本即可看到已更改的配置文件, 提交到主分支即可.
-
.github/NMS_TEMPLATE/*.template 模板,这些模板中内置了如 ${{name}} 这样的变量, 这些变量的来源是 project.yml 中的实体节点, 半自动脚本运行时将会替换变量完成最终配置文件.
-
.github/workflows/*.yml, 这些文件是管道真正起作用的最终配置文件.
- 一部分是自动化脚本转换而来的.
- 一部分是本身就存在的,半自动化脚本并未完全收录这些配置, 因为有些配置都是写死不用改或者改动甚小, 因此不在半自动化脚本覆盖范围内.
scanner.bat/sh
-
1. 该脚本是管道操作的常用脚本, 它负责调用 Workflow.Initialization 项目来完成 project.yml 的文件生成及节点控制, 实际上半自动化是基于 .NET 程序来完成的.
-
2. 您在项目增减节点之后需要运行它, 以完成这个新项目的配置或更新管道配置.
-
3. 在您更改 project.yml 文件后需要运行它, 它将把 project.yml 文件节点转换真正的管道配置.
Project.yml
我们对配置做了集中管理并存放在 project.yml 文件中,集中配置包括项目节点的增减/折叠/忽略/全局配置等功能.详解如下:
-
1. 增减, 当您新创建/删除一个项目的时候, 运行项目根目录下的脚本 scanner.bat/sh, 脚本会向配置文件 project.yml 追加或删除节点(不破坏已有的配置).
重新生成工程配置文件 project.yml:
-
2. 全局配置, 目前的全局功能配置仅有一个:global_labels. 该配置节点的值为一组 label 实体, 意思是在当前节点下的所有项目在发现 PR 时, 为其打上全局标签. 假设 src 节点下有全局配置 : label: pr_src , 且您的 src 下有10个项目, 当这10个项目任意一个有人提交 PR 时, PR 会打上 pr_src 标记.
-
3. 折叠, 配置节点属性较多, 如果仅仅想使用全局功能而不配置其他, 可以将 project.yml 项目节点 is_folded 的值设置为 true.
再一次运行 scanner.bat/sh 使其生效
-
4. 忽略, 理同折叠, 只不过忽略是完全忽视这个工程节点, is_ignored 为 ture 的项目不会享有任何管道的功能. 重新运行脚本使其生效,这些被忽视的节点将被记录在配置文件中, 删除可使其重新享有管道功能.
Using 隐式输出
感谢 Newbe 俞佬的需求, 项目源码管道增加了 隐式 using 输出的功能.
半自动脚本将根据 project.yml 的配置节点来控制隐式 using 自动生成功能.
- using_output:
enable: true
ignores:
- System
- System.Runtime.CompilerServices
- System.Reflection
选项配置:
- enable:true, 启用 using 输出, 所有公有的 类/结构体/接口/记录/枚举 所在的命名空间都将输出到 Targets/Project.Usings.targets 文件中.
- ignores, 需要被排除的 using 引用代码.
由于涉及到 NUGET 打包发布,因此 csproj 工程文件的内容可能也会随之变动.
依赖检测
属性解释
如图所示, project配置的每个项目下都会有依赖节点:
- type: 您依赖包的服务名称, 比如 .net 依赖来自于 nuget, 其他语言依赖比如 npm/pip/github-actions/gomod/composer/bundler 等等.
- interval: 检测周期, daily 工作日 , weekly 每周一, monthly 每月第一天.
- commit_prefix: 机器人提交 PR 的前缀.
- special_time: 指定时间 "09:00".
- special_time_zone: 指定时区 比如 "Asia/Harbin" 哈勒斌时区.
- labels: 机器人提交 PR 时打上的标签.
- ignore: 忽略依赖项(数组)
- name: 希望被忽略的依赖包的名称
- version: 希望被忽略的依赖包版本 ["1.0.0","2.*"]
- version-type:希望被忽略版本的类型,["version-update:semver-major","version-update:semver-minor","version-update:semver-patch"]
SemVer 约定(语义化版本)
"version-update:semver-patch" 这玩意看不懂是吧?那看这个"Major.Minor.Patch"/"1.3.12"
比如, 有一个包更新超级快,但是它得更新很鸡肋, 比如改个注释发个版本, 改个变量名发个版本, 一周时间内从 1.3.0 发到 1.3.105, 你想忽视这种非功能更新怎么办,
配置 version-type:["version-update:semver-patch"] 忽视掉补丁更新这一级别, 也就是让机器人只关注 1.3 而忽视 1.3.x.
NUGET 是遵守 SemVer 约定的.
BOT互动
当 BOT 提交 PR 时, 您可以与其互动指令,已完成后续功能:
案例:
结尾
以上便是半自动脚本和项目配置的简单讲解, 下一篇将进入具体管道功能的实战配置.
学习与使用
1. 将项目 fork 到你的仓库中, 然后 Setting 作为模板.
