Skip to content

Commit

Permalink
文档(工程设计): 优化 README.md 和许可协议
Browse files Browse the repository at this point in the history 
README.md
  • Loading branch information
@ziyi2
ziyi2 committed Oct 25, 2023
2 parents 074a3de + cfc9701 commit 12c30ee
Show file tree
Hide file tree
Showing 5 changed files with 116 additions and 284 deletions.
21 changes: 21 additions & 0 deletions LICENSE
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2023-present ziyi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
288 changes: 34 additions & 254 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,270 +1,50 @@
# Github Actions
# Micro Framework

ci 的流程和解释如下所示：
<p align="left">
<!-- https://github.com/OWNER/REPOSITORY/actions/workflows/WORKFLOW-FILE/badge.svg -->
<a href="https://github.com/ziyi2/micro-framework/actions/workflows/ci.yml"><img src="https://github.com/ziyi2/micro-framework/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
<a href="https://github.com/ziyi2/micro-framework/actions/workflows/cd.yml"><img src="https://github.com/ziyi2/micro-framework/actions/workflows/cd.yml/badge.svg" alt="CD Status"></a>
<a href='https://coveralls.io/github/ziyi2/micro-framework?branch=master'><img src='https://coveralls.io/repos/github/ziyi2/micro-framework/badge.svg?branch=master' alt='Coverage Status' /></a>
<a href="https://www.npmjs.com/package/ziyi-micro-framework"><img alt="npm" src="https://img.shields.io/npm/v/ziyi-micro-framework"></a>
</p>

``` yml
# 当前的 yml（.yaml） 文件是一个 workflow，必须放置在项目的 .github/workflow 目录下
Micro Framework 是[《深入浅出微前端》](https://juejin.cn/book/7258893482318626868)小册衍生出来的一个微前端示例框架。

# name: 当前 workflow 的名称
name: ci
## 特性

# on: 指定 workflow 触发的 event
#
# event 有以下几种类型
# - webhook
# - scheduled
# - manual
on:
# push: 一个 webhook event，用于提交代码时触发 workflow，也可以是触发列表，例如 [push, pull_request]
- 基于 single-spa 进行封装
- 基于 iframe 进行隔离设计
- 提供 Loader 的扩展机制
- ...

# workflows 触发的 event 大部分是基于 webhook 配置，以下列举几个常见的 webhook:
# - delete: 删除一个 branch 或 tag 时触发
# - fork / watch: 某人 fork / watch 项目时触发（你问有什么用，发送邮件通知不香吗？）
# - pull_request: 提交 PR 时触发
# - page_build: 提交 Github Pages-enabled 分支代码时触发
# - push: 提交代码到特定分支时触发
# - registry_package: 发布或跟新 package 时触发
## 安装

# 更多 webhook 可查看 https://docs.github.com/zh/actions/using-workflows/events-that-trigger-workflows
``` bash
# CommonJS 库包安装
npm i ziyi-micro-framework --save

# 从这里可以看出 Git Actions 的一大特点就是 Gihub 官方提供的一系列 webhook
push:
# branches: 指定 push 触发的特定分支，这里你可以通过列表的形式指定多个分支
branches:
- demo/**
- feat/**
- fix/**
#
# branches 的指定可以是通配符类型，例如以下配置可以匹配 refs/heads/releases/10
# - 'releases/**'
#
# branches 也可以使用反向匹配，例如以下不会匹配 refs/heads/releases/10
# - '!releases/**'
#
# branches-ignore: 用于指定当前 webhook 不触发的分支
#
# tags: 用于指定当前 webhook 触发的 tag
#
# tags:
# - v1 # Push events to v1 tag
# - v1.* # Push events to v1.0, v1.1, and v1.9 tags
#
# tags-ignore: 类似于 branches-ignore
#
# paths、paths-ignore...
#
# 更多关于特定过滤模式可查看 https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
#
# 其他的 webhook 控制项还包括 types（不是所有的 webhook 都有 types），例如已 issues 为例，可以在 issues 被 open、reopened、closed 等情况下触发 workflow
# 更多 webhook 的 types 可查看 https: //docs.github.com/en/actions/reference/events-that-trigger-workflows#webhook-events
#
# on:
# issues:
# types: [opened, edited, closed]

# 除此之外如果对于每个分支有不同的 webhook 触发，则可以通过以下形式进行多个 webhook 配置
#
# push:
# branches:
# - master
# pull_request:
# branches:
# - dev
#
# 除了以上所说的 webhook event，还有 scheduled event 和 manual event
# scheduled event: 用于定时构建，例如最小的时间间隔是 5 min 构建一次
# 具体可查看 https: //docs.github.com/en/actions/reference/events-that-trigger-workflows#scheduled-events

# env: 指定所有 job 和 step 通用的环境变量（在 job 中或者 steps 中也可以通过 env 配置自己的环境变量）
#
# defaults: 当前所有 job 的默认配置

# jobs: 一个 workflow 由一个或多个 job 组成
jobs:
# job id: 是 job 的唯一标识，可以通过 _ 进行连接，例如: my_first_job，例如这里的 test 就是一个 job id
test:
# name: 在 Github 中显示的 job 名称
name: CI 执行流程
#
# needs: 用于继发执行 job，例如当前 job build 必须在 job1 和 job2 都执行成功的基础上执行

# jobs:
# job1:
# job2:
# needs: job1
# job3:
# needs: [job1, job2]
#
# runs-on: job 运行的环境配置，包括:
# - windows-latest
# - windows-2019
# - ubuntu-20.04
# - ubuntu-latest
# - ubuntu-18.04
# - ubuntu-16.04
# - macos-latest
# - macos-10.15
# - self-hosted（本地机器，具体可查看 https://docs.github.com/zh/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow）

runs-on: ubuntu-latest

#
# outputs: 用于输出信息
#
# env: 用于设置当前 job 的环境变量
#
# defaults: 当前所有 step 的默认配置

# if: 满足条件执行当前 job

# steps: 一个 job 由多个 step 组成，step 可以
# - 执行一系列 tasks
# - 执行命令
# - 执行 action
# - 执行公共的 repository
# - 在 Docker registry 中的 action
steps:
#
# id: 类似于 job id
#
# if: 类似于 job if
#
# name: 当前 step 的名字
- name: 下载 Github 仓库
#
# uses: 用于执行 action
#
# action: 可以重复使用的单元代码
# - 为了 workflow 的安全和稳定建议指定 action 的发布版本或 commit SHA
# - 使用指定 action 的 major 版本，这样可以允许你接收 fixs 以及 安全补丁并同时保持兼容性
# - 尽量不建议使用 master 版本，因为 master 很有可能会被发布新的 major 版本从而破坏了 action 的兼容性
# - action 可能是 JavaScript 文件或 Docker 容器，如果是 Docker 容器，那么 runs-on 必须指定 Linux 环境
#
# 指定固定 commit SHA
# uses: actions/setup-node@74bc508
# 指定一个 major 发布版本
# uses: actions/setup-node@v1
# 指定一个 minor 发布版本
# uses: actions/setup-node@v1.2
# 指定一个分支
# uses: actions/setup-node@master
# 指定一个 Github 仓库子目录的特定分支、ref 或 SHA
# uses: actions/aws/ec2@master
# 指定当前仓库所在 workflows 的目录地址
# uses: ./.github/actions/my-action
# 指定在 Dock Hub 发布的 Docker 镜像地址
# uses: docker://alpine: 3.8
# A Docker image in a public registry
# uses: docker:/gcr.io/cloud-builders/gradle

# checkout action 主要用于向 github 仓库拉取源代码（需要注意 workflow 是运行在服务器上，因此需要向远程的 github 拉取仓库源代码）
# 它的功能包括但不限于
# - Fetch all history for all tags and branches
# - Checkout a different branch
# - Checkout HEAD^
# - Checkout multiple repos (side by side)
# - Checkout multiple repos (nested)
# - Checkout multiple repos (private)
# - Checkout pull request HEAD commit instead of merge commit
# - Checkout pull request on closed event
# - Push a commit using the built-in token

# checkout action: https: //github.com/actions/checkout
uses: actions/checkout@v4
# with: action 提供的输入参数
# with:
# 指定 checkout 的分支、tag 或 SHA
# 如果默认不指定，则指向触发工作流所在分支的 SHA
# When checking out the repository that triggered a workflow, this defaults to the reference or SHA for that event.
# 更多 checkout action 的配置可查看 https://github.com/actions/checkout#usage
# ref: feat/ci

#
# run: 使用当前的操作系统的默认的 non-login shell 执行命令行程序
# 运行单个脚本
# run: npm install
# 运行多个脚本
# run: |
# npm ci
# npm run build
#
# working-directory: 用于指定当前脚本运行的目录
# working-directory: ./temp
#
# shell: 可以指定 shell 类型进行执行，例如 bash、pwsh、python、sh、cmd、powershell
# shell: bash
#
# env: 除了可以设置 workflow 以及 job 的 env，也可以设置 step 的 env（可以理解为作用域不同，局部作用域的优先级更高）
#
# comtinue-on-error: 默认当前 step 失败则会阻止当前 job 继续执行，设置 true 时当前 step 失败则可以跳过当前 job 的执行

# - name: 缓存 node_modules 依赖
# # cache action: https://github.com/actions/cache
# # cache 在这里主要用于缓存 npm，提升构建速率
# uses: actions/cache@v3
# # npm 缓存的路径可查看 https://docs.npmjs.com/cli/cache#cache
# # 由于这里 runs-on 是 ubuntu-latest，因此配置 ~/.npm
# with:
# # 指定缓存和还原的路径
# path: ~/.npm
# # key 中定义缓存标志，runner.os 指当前环境的系统。
# # 这里使用 package-lock.json 的内容生成 Hash 值作为缓存的 key 值
# # 一旦 package-lock.json 发生变化，则会导致 Hash 值变化，从而变更缓存内容
# key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
# # 备用 key，如果 key 没有命中缓存，则可以使用 restore-keys 进行备用缓存匹配
# restore-keys: |
# ${{ runner.os }}-node-
# ES Module 库包安装
npm i ziyi-micro-framework-es -save
```

# github-script action: https://github.com/actions/github-script
# 在 workflow 中使用 Script 语法调用 Github API 或引用 workflow context
# - uses: actions/github-script@v6
# id: my-script
# with:
# result-encoding: string
# retries: 3
# script: |
# github.rest.issues.get({
# issue_number: context.issue.number,
# owner: context.repo.owner,
# repo: context.repo.repo,
# })
## 使用

# setup-node action: https://github.com/actions/setup-node
# 配置 Node 执行环境（当前构建的服务器默认没有 Node 环境，可以通过 Action 安装 Node）
# 需要注意安装 Node 的同时会捆绑安装 npm，如果想了解为什么会捆绑，可以 Google 一下有趣的故事哦
# 因此使用了该 action 后就可以使用 npm 的脚本在服务器进行执行啦
- name: 下载和安装 Node 环境
uses: actions/setup-node@v3
with:
# 在 package.json 的 engines 中我们配置了 "node": ">=16.18.1"
# 因此这里对安装的 Node 进行版本限定
node-version: "16.x"
暂无使用方法，正在设计中...

- name: 安装依赖
# 需要注意 npm ci 和 npm i 的区别
run: npm ci
## 贡献指南

- name: 代码校验
run: npm run lint
如果该微前端框架代码存在优化空间，希望大家可以指正。可以通过提 [Issues](https://github.com/ziyi2/micro-framework/issues) 的形式告知，也可以通过 Pull Request 的形式提交指正代码，作者会对代码进行 Review，如果通过会合并大家的代码，也可能告诉大家为什么不能接受这样的修改，并最终关闭它。

- name: 单元测试
run: npm test
在提交一个 Pull Request 之前，请确保你按照以下的步骤来做：

- name: 文档构建
run: npm run docs:build
- Fork 仓库
- 创建分支进行修改
- 使用 Angular 规范的提交说明
- 更新源码的同时更新相应的 VuePress 说明文档
- 确保代码通过 CI 流程

- name: 代码构建
run: npm run build
## 许可协议

#
# timeout-minutes: 一个 job 执行的最大时间，默认是 6h，如果超过时间则取消执行
#
# strategy.matrix: 例如指定当前 job 的 node 版本列表、操作系统类型列表等
# strategy.fail-fast
# strategy.max-parallel
# continue-on-error: 一旦当前 job 执行失败，那么 workflow 停止执行。设置为 true 可以跳过当前 job 执行
# container: Docker 容器配置，包括 image、env、ports、volumes、options 等配置
#
# services: 使用 Docker 容器 Action 或者 服务 Action 必须使用 Linux 环境运行
[MIT](https://opensource.org/license/mit/)

```
Copyright (c) 2023-present ziyi
17 changes: 10 additions & 7 deletions build/release.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,9 @@ class Release extends Base {
async check() {
const targets = this.getTargets();
if (!targets?.length) return;
// 本地发布流程需要，如果是 CD 流程，则可以跳过该检测流程
// 单元测试检查
this.checkUnitTest();
// this.checkUnitTest();
// 发布分支检测
await this.checkBranch();
// 发布文件检测
Expand Down Expand Up @@ -98,12 +99,14 @@ class Release extends Base {
);
process.exit(1);
}
// 确保当前的 master 分支的文件没有变更
const status = await git.status();
if (status?.files?.length) {
this.logError("[发布失败]: 不允许更改本地 master 代码！");
process.exit(1);
}
// 确保当前的 master 分支的文件没有变更（CD 流程需要自动生成 API 文档信息，因此会产生变更，这里跳过检测）
// TODO:
// const status = await git.status();
// console.log("status: ", status);
// if (status?.files?.length) {
// this.logError("[发布失败]: 不允许更改本地 master 代码！");
// process.exit(1);
// }
// 确保当前 master 分支的代码和远程代码一致（防止本地偷偷发布没有 Code Review 的代码）
// 有没有其他方式可以比较本地 master 和远程 master 分支是一致的？
const { stdout } = shell.exec("git diff origin/master master", {
Expand Down

0 comments on commit 12c30ee

Please sign in to comment.