diff --git a/.github/workflows/CD.yaml b/.github/workflows/CD.yaml index 3ab29d40b..9a4c99b97 100644 --- a/.github/workflows/CD.yaml +++ b/.github/workflows/CD.yaml @@ -11,14 +11,12 @@ on: - next workflow_dispatch: - # 环境变量 env: ## vercel VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} - jobs: ## 部署到Github-Pages deploy-github: diff --git a/.github/workflows/CI.yaml b/.github/workflows/CI.yaml index 3b8b558e3..0b4791f1b 100644 --- a/.github/workflows/CI.yaml +++ b/.github/workflows/CI.yaml @@ -1,7 +1,6 @@ ## 代码CI快速集成流水线，lint、fix、build ## 注意： 只在142vip/JavaScriptCollection时执行 - name: CI ## 触发条件 on: @@ -75,7 +74,6 @@ jobs: run: | ./scripts/bundle build_proxy - Build-Docker-Image: name: "构建Docker镜像" ## macos不支持docker的使用 @@ -108,7 +106,6 @@ jobs: --password=${{ secrets.DOCKER_PASSWORD }} \ ${{env.REGISTRY}} - - name: Install Dependencies run: | ./scripts/ci diff --git a/docs/manuscripts/develop-skill/code-manager/CI-CD.md b/docs/manuscripts/develop-skill/code-manager/CI-CD.md index bba333d05..65c35afc4 100644 --- a/docs/manuscripts/develop-skill/code-manager/CI-CD.md +++ b/docs/manuscripts/develop-skill/code-manager/CI-CD.md @@ -4,3 +4,158 @@ permalink: /manuscripts/develop-skill/code-manager/ci-cd.html --- # 持续集成、持续交付 + +## 最佳实践 + +### 持续集成 + +```yaml +## 代码CI快速集成流水线，lint、fix、build +## 注意： 只在142vip/JavaScriptCollection时执行 + +name: CI +## 触发条件 +on: + # 提PR到next分支触发CI + pull_request: + branches: + - next + push: + branches: + - next + + # 手动触发部署 + workflow_dispatch: + + schedule: + - cron: "0 0 1 * *" + +jobs: + Base-Build: + name: "基础编译构建" + runs-on: ubuntu-latest + if: github.repository == '142vip/JavaScriptCollection' && github.event_name == 'pull_request' + permissions: + actions: read + pull-requests: read + + steps: + - name: Checkout Code + uses: actions/checkout@v4 + with: + persist-credentials: false + # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录 + fetch-depth: 0 + + ## 安装PNPM + - name: PNPM Install + uses: pnpm/action-setup@v2 + with: + version: 8 + + ## 安装Node环境 + - name: Install Node.js + uses: actions/setup-node@v3 + with: + node-version: 18.18.0 + ## 淘宝镜像加速 + registry-url: 'https://registry.npmmirror.com' + ## 缓存 + cache: 'pnpm' + + ## 下载依赖，并执行初始化脚本：钩子函数、思维导图构建 + - name: Install Dependencies + run: | + ./scripts/ci + + - name: Code LintFix + run: | + ./scripts/lint + + - name: Build Site + run: | + ./scripts/bundle build + + - name: Build Site With Proxy + run: | + ./scripts/bundle build_proxy + +``` + +### 持续交付 + +```yaml + +## CD交付流水线 +## - 部署到Github Pages +## - 部署到Vercel托管平台 +## - 发布新的Github Release +## 参考资料：https://v2.vuepress.vuejs.org/zh/guide/deployment.html#github-pages + +name: CD +on: + push: + branches: + - next + workflow_dispatch: + +jobs: + ## 版本发布 + release: + name: "创建Github发布" + runs-on: ubuntu-latest + ## 主库next且执行release更新时执行 + if: github.repository == '142vip/JavaScriptCollection' && startsWith(github.event.head_commit.message, 'chore(release):') + + steps: + - name: Checkout Code + uses: actions/checkout@v4 + with: + persist-credentials: false + # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录 + fetch-depth: 0 + + ### 打成压缩包 + - name: Create Zip Package + run: | + zip -r JavaScriptCollection.zip . \ + -x "node_modules/*" \ + -x ".git/*" + + # 提取版本号 + - name: Get New Version Number + id: releaseVersion + run: | + echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT + + # 创建发布版本 + - name: Create New Release + id: createRelease + uses: actions/create-release@latest + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: v${{ steps.releaseVersion.outputs.version }} + release_name: v${{ steps.releaseVersion.outputs.version }} + body: | + Release ${{ steps.releaseVersion.outputs.version }} + + ### Features + + ### Bug Fixes + + ## 更新资源 + - name: Upload Resource Assets + uses: actions/upload-release-asset@latest + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.createRelease.outputs.upload_url }} + asset_path: ./JavaScriptCollection.zip + asset_name: JavaScriptCollection.zip + asset_content_type: application/zip + + +``` + +## 参考资料 diff --git a/docs/manuscripts/develop-skill/code-manager/git.md b/docs/manuscripts/develop-skill/code-manager/git.md index a25cbf02c..10b6b6a15 100644 --- a/docs/manuscripts/develop-skill/code-manager/git.md +++ b/docs/manuscripts/develop-skill/code-manager/git.md @@ -1,13 +1,24 @@ --- title: Git的使用 permalink: /manuscripts/develop-skill/code-manager/git.html -headerDepth: 3 +headerDepth: 2 --- # Git的使用 -## 简单介绍 +**到目前为止，当今世界上使用最广泛的现代版本控制系统是 Git**。Git 是一个成熟的、积极维护的开源项目，最初由 Linux 操作系统内核的著名创建者 Linus Torvalds 于 2005 年开发。 +有海量软件项目依赖 Git 进行版本控制，包括商业项目和开源项目。使用过 Git 的开发人员在可用的软件开发人才库中占有很好的比例，它在各种操作系统和 IDE（集成开发环境）上都能很好地运行。 -- 官网: +Git 采用分布式架构，是 DVCS（分布式版本控制系统）的示例。在 Git 中，每个开发人员的代码工作副本也是一个可以包含所有变更完整历史记录的存储库， +而不是像曾经流行的 CVS 或 Subversion（也称为 SVN）等版本控制系统那样，只有一个地方存放软件的完整版本历史记录。 + +除了分布式外，Git 的设计还考虑了`性能`、`安全性`和`灵活性`。 + +## 版本控制 + +版本控制，也称为源代码控制，是一种跟踪和管理软件代码变更的实践。版本控制系统是软件工具，可帮助软件团队管理源代码随时间推移而发生的变更。 +随着开发环境的加速，版本控制系统可以帮助软件团队更快、更智能地工作。它们对于 DevOps 团队特别有用，因为它们可以帮助该团队缩短开发时间并提高部署成功率。 + +**版本控制软件在特殊类型的数据库中跟踪对代码的每一次修改。如果犯了错误，开发人员可以回退并比较代码的早期版本，以帮助修复错误，同时最大限度地减少对所有团队成员的干扰。** ![](images/git.png) @@ -24,29 +35,60 @@ Git 区域理解: - `工作区`：这个一般就是我们写代码的地方 -## 常用命令 +## 安装Git -### git stash +### Mac OS X 系统 + +#### 利用官方镜像 + +下载最新的[Git for Mac 安装程序](https://sourceforge.net/projects/git-osx-installer/files/)，按照提示安装即可。 + +#### 利用Homebrew ```bash -## 储存变更 -git stash -git stash save 'xxx': +## Homebrew安装Git +brew install git -## 查看储存区所有提交列表 -git stash list +## 查看版本，检查是否安装成功 +git --version +``` -## 弹出并应用最近的一次储存区的代码提交 -git stash pop +### Windows系统 -## 删除某次储存记录 -git stash drop stash@{n} +利用官方安装包，下载最新的[Git for Windows 安装程序](https://gitforwindows.org/)，按照提示安装即可。 -## 清楚所有 stash 信息 -git stash clear +### Linux系统 + +#### Debian/Ubuntu (apt-get) + +Git 软件包可通过 `apt` 获得 + +```bash +## 安装包更新 +sudo apt-get update + +## 安装Git +sudo apt-get install git +``` + +#### Fedora (dnf/yum) +Git 软件包可以通过 `yum` 和 `dnf` 获得： + +```bash +## dnf安装git +sudo dnf install git + +## yum安装git +sudo yum install git ``` +## 常用命令 + +### git init + +将目录进行git仓库初始化 + ### git clone ```bash @@ -57,9 +99,29 @@ git clone xxx.git git clone xxx.git -b branch1 ``` -### git init +### git stash -将目录进行git仓库初始化 +```bash +## 暂存变更 +git stash +git stash save 'xxx': + +## 查看暂存区所有提交列表 +git stash list + +## 弹出并应用最近的一次暂存区的代码提交 +git stash pop + +## 删除某次暂存记录 +git stash drop stash@{n} + +## 查看暂存内容变更 +git stash show + +## 清楚所有 stash 信息 +git stash clear + +``` ### git remote @@ -151,40 +213,34 @@ git branch -D git branch -m ``` -## 分支命名规范 +## 分支规范 -#### 版本命名格式：X.Y.Z +### 分支命名 -- **修订版号 Z**（x.y.Z | x > 0）向下兼容的修正时才递增，线上bug修复。 -- **次版本号 Y**（x.Y.z | x > 0）向下兼容的新功能出现时递增，日常迭代。 -- **主版本号 X**（X.y.z | X > 0）不兼容的修改被加入公共 API 时递增，大版本更新。 +- 功能迭代：`feat/xxx` +- 提测bugfix：`fix/xxx` +- 线上问题紧急修复：`hotfix/xxx` -#### 上游优先 +### 上游优先 - `master` 作为主分支 一般稳定版本 - 其他分支皆从 `master` 分支`衍生` - 注意与传统分支策略区别 -#### 多环境长线分支 +### 多环境长线分支 - `master`：开发稳定分支 - `test`：测试测试环境，一般对应测试服，可以详细分为测试--->预发 - `prod`：线上环境，一般对应正式服【重要】 -#### 分支类型 +### 分支类型 -- 功能迭代分支：`feature` +- 功能迭代分支：`feat` - 提测后bugfix分支：`bugfix` - 线上问题紧急修复：`hotfix` - 所有开发动作在短期分支上完成 -**长线分支只允许mr、禁止push、feature、bugfix 从 `master` 分支拉取，hotfix 从 `master`(线上稳定分支) 拉取。**分支目的完成后要求及时删除 - -#### 分支命名 - -- 功能迭代：feature/xxx -- 提测bugfix：fix/xxx -- 线上问题紧急修复：hotfix/xxx +**长线分支只允许MR、禁止push、feature、bugfix 从 `master` 分支拉取，hotfix 从 `master`(线上稳定分支) 拉取。** 分支目的完成后及时删除 ## 提交规范 @@ -231,8 +287,6 @@ subject是 commit 目的的简短描述，不超过50个字符。 - 第一个字母小写 - 结尾不加句号（.） -#### Body - Body 部分是对本次 commit 的详细描述，可以分成多行，每行尽量不超过72个字符。例如： ```text @@ -258,6 +312,12 @@ Closes #234 Closes #123, #245, #992 ``` +## 版本格式X.Y.Z + +- **修订版号 Z**（x.y.Z | x > 0）向下兼容的修正时才递增，线上bug修复。 +- **次版本号 Y**（x.Y.z | x > 0）向下兼容的新功能出现时递增，日常迭代。 +- **主版本号 X**（X.y.z | X > 0）不兼容的修改被加入公共 API 时递增，大版本更新。 + ## 配置用户名和邮箱 ```bash @@ -275,13 +335,13 @@ git config --list ## 修改历史提交信息 -#### 查看提交日志 +### 查看提交日志 ```bash git log ``` -#### rebase到指定结点 +### rebase到指定结点 ```bash git rebase -i xxx @@ -290,26 +350,26 @@ git rebase -i xxx git rebase -i HEAD~1 ``` -#### 进入编辑界面，记录着commit的信息 +### 进入编辑界面，记录着commit的信息 pick---->edit 并保存，即使用`wq`退出 -#### 重新设置用户名和邮箱 +### 重新设置用户名和邮箱 ```bash ## 用户信息 git commit --amend --author="chufan " ``` -#### 结束rebase +### 结束rebase ```bash git rebase --continue ``` -#### 强制推送到目标分支 +### 强制推送到目标分支 ```bash git push -f @@ -329,9 +389,9 @@ git push origin --tags #推送指定本地tag到远程 git push origin - ``` ## 参考资料 -- +- 官网： +- diff --git a/docs/manuscripts/develop-skill/code-style/engineering-lint.md b/docs/manuscripts/develop-skill/code-style/engineering-lint.md new file mode 100644 index 000000000..e164db30d --- /dev/null +++ b/docs/manuscripts/develop-skill/code-style/engineering-lint.md @@ -0,0 +1,147 @@ +--- +title: 工程化规范 +permalink: /manuscripts/develop-skill/code-style/engineering-lint.html +--- + +# 工程化规范 + +前面提到的Eslint、Prettier是在工程化建设中使用非常高频的，主要是用来处理一些代码层面的约束，确保在项目中编码风格一致。 + +但当项目体量、人员协同上去后，单纯的约束代码风格还是不够的，需要指定标准的规范来对项目进行工程化管理，例如：对提交、更改的内容做风格约束。 + +这里，我整理了一些自己在项目中常用的一些规范，分开讨论 + +## 代码校验 + +利用Eslint来校验js、ts代码，如果是前端还可以配置vue对应规则 + +```bash +## 校验js、ts、vue代码 +eslint --ext .js,.ts,.vue --ignore-path .gitignore . + +## 添加--fix参数，可以做到自动修正 +eslint --fix --ext .js,.ts,.vue --ignore-path .gitignore . +``` + +## 文档校验 + +除了写代码外，项目中会有一些markdown文档，特别是对于文档类型项目markdown文档就更多了，但风格却很难保证，因此可以利用`markdownlint-cli`模块进行校验、修正 + +### 安装 + +```bash +## 开发环境安装依赖 +pnpm install markdownlint-cli -D +``` + +### 配置规则 + +在项目根目录新建`.markdownlint.js`文件，配置markdown的一些规则，例如： + +@[code js](~@/.markdownlint.js) + +### 配置忽略 + +由于`**/*.md`是匹配项目中所有markdown文档，很明显存在有些目录时不需要校验的，例如：`node_modules`目录，因此非常有必要配置`markdownlint-cli` +的忽略文件`.markdownlintignore`，避免校验不必要的文档。 + +在项目根目录新建`.markdownlintignore`文件，配置markdown的忽略规则，例如： + +@[code txt](~@/.markdownlintignore) + +### 使用 + +```bash +## 校验markdown文档 +markdownlint '**/*.md' -c .markdownlint.js -p .markdownlintignore + +## 添加--fix参数，可以做到自动修正 +markdownlint '**/*.md' -c .markdownlint.js -p .markdownlintignore --fix +``` + +## 提交校验 + +当我们对代码、文档都做了一些校验，统一格式后一般是需要使用Git进行变更提交的。 +对于上面的一些lint操作，不可能每次都手动执行，**因此就非常需要在提交之前先对仓库中的代码、文档做一些校验，并且这些操作是自动执行的** + +这个时候就需要使用到Git的hooks钩子函数，在`pre-commit`之前执行一些指令，打开`git/hooks`目录里面的内容，可以发现以下文件 + +- applypatch-msg.sample +- pre-push.sample +- commit-msg.sample +- pre-rebase.sample +- post-update.sample +- prepare-commit-msg.sample +- pre-applypatch.sample +- update.sample +- pre-commit.sample + +这些钩子都是样例，去掉`.sample`在提交时就能触发对应的钩子函数。 + +这里推荐`husky`模块，它可以很好地校验提交信息、运行命令，很好的确保commit、push规范 + +### 安装husky + +```bash +## 生产环境安装 +pnpm install husky -D +``` + +### 配置hook + +```bash +## 在git hook文件中写入npm test命令 +npx husky add .husky/pre-commit "npm test" +``` + +这个时候，打开`.husky/pre-commit`文件，可以发现`npm test`命令，当进行git commit时会自动执行`npm test`命令，校验失败则终止`commit`操作 + +## 内容自动格式化 + +可以发现，上面的`husky`模块只是校验提交信息、运行一些既定的命令，例如：执行Eslint校验。但往往随着工程中项目较多，项目级别的Lint会消耗很多时间，且对于仓库来说： + +> 提交到仓库中的代码是需要遵守规范的，也就是lint完成之后的 + +那有没有工具，可以对Git的提交内容做校验，换句话说：“只校验更改的”。这个时候就非常推荐`lint-staged`,它可以实现对提交的变更做一些操作，可以解决husky执行hook时全局操作耗时问题 + +### 安装lint-staged + +```bash +## 开发环境安装 +pnpm install lint-staged -D +``` + +### 配置规则 + +在项目根目录中新建`.lintstagedrc.js`文件 + +@[code js](~@/.lintstagedrc.js) + +以上规则是： + +- 对js、ts、md文件进行ci校验 +- 将格式化后端内容自动提交,执行`git add`操作，避免多次commit + +当然，`lint-staged`规则的配置还支持很多方式，例如： + +- `.lintstagedrc.json` +- `.lintstagedrc.yaml` +- `.lintstagedrc.yml` + +## 最佳实践 + +以上只是简单的介绍 `git hooks` 、`hushy`、`lint-staged`，在本仓库中已投入应用，将讲这些操作按照流程拼接在一起，其实就有了工程化的一些痕迹 + +这里操作都是可以划分为CI，即：持续集成，Git在commit变更时触发hook，会做一下操作： + +- 校验commit提交信息 +- 校验提交的代码、文档，对于不符合规范的自动修正 +- 修正失败时，commit操作就终止 + +可以总结到： **husky是管理Git hooks，lint-staged是对Git提交做检验，验证的模块** + +## 参考资料 + +- +- +- diff --git a/docs/manuscripts/develop-skill/code-style/eslint.md b/docs/manuscripts/develop-skill/code-style/eslint.md index 6a0ba8247..f5e461638 100644 --- a/docs/manuscripts/develop-skill/code-style/eslint.md +++ b/docs/manuscripts/develop-skill/code-style/eslint.md @@ -6,23 +6,20 @@ permalink: /manuscripts/develop-skill/code-style/eslint.html ## 基础使用 -- 配置eslint - -- 生产环境安装eslint +### 安装 ```bash ## 安装eslint pnpm i eslint -D - ``` +### 初始化 + 执行eslint命令，根据cli进行选择配置 ```bash - # 执行初始化 ./node_modules/.bin/eslint --init - ``` 会自动生成`.eslintrc.js`文件，例如： @@ -31,20 +28,19 @@ pnpm i eslint -D 其中`rules`对象可以自定义规则 +### 配置eslint + 相关`eslint`包`package.json`文件如下： ```package.json "@typescript-eslint/eslint-plugin": "^5.53.0", "@typescript-eslint/parser": "^5.53.0", -"cz-git": "^1.4.1", "eslint": "^8.34.0", "eslint-config-standard": "^17.0.0", "eslint-plugin-import": "^2.25.2", "eslint-plugin-n": "^15.0.0", "eslint-plugin-promise": "^6.0.0", "eslint-plugin-vue": "^9.9.0", -"husky": "^8.0.3", -"typescript": "^3.9.10", ``` ## 参考资料 diff --git a/docs/manuscripts/develop-skill/code-style/prettier.md b/docs/manuscripts/develop-skill/code-style/prettier.md index 42607f565..ce0c950f7 100644 --- a/docs/manuscripts/develop-skill/code-style/prettier.md +++ b/docs/manuscripts/develop-skill/code-style/prettier.md @@ -2,6 +2,7 @@ title: Prettier permalink: /manuscripts/develop-skill/code-style/prettier.html --- + # Prettier ## 基础使用 diff --git a/docs/manuscripts/develop-skill/develop-skill.sidebar.ts b/docs/manuscripts/develop-skill/develop-skill.sidebar.ts index f4056aaaa..5050cc2f7 100644 --- a/docs/manuscripts/develop-skill/develop-skill.sidebar.ts +++ b/docs/manuscripts/develop-skill/develop-skill.sidebar.ts @@ -64,6 +64,10 @@ export const developSkillSidebar = [ { text: 'Prettier', link: 'prettier.md' + }, + { + text: '工程化规范', + link: 'engineering-lint.md' } ] }