快来利用 Github 这个功能来建立让本身满意的项目模版吧

我认可我实在想不出更好的标题了，由于本文涉及到的内容比较宽泛。但我保证，本文会尽量作到抛砖引玉的效果。不只仅是建立项目模版，写项目的时候须要考虑的东西本文也适合。

本文主要会讲如下几个内容：

1. Github 的模版仓库功能
2. 开源项目（模版）要考虑的 9 个工程化要素
3. 一些建立项目（模版）时提高效率的技巧

阅读过程当中能够同时参考我写的一个模版仓库样例，若有经常使用 TypeScript 和 VSCode 的读者，食用起来会更佳。

目录

• 背景
• 如何作到满意
  • TypeScript
    • Tips
  • 编码规范
    • Tips
  • 测试框架
    • Tips
  • Commit 规范
  • CI / CD
  • 文档
  • CHANGELOG
  • 协议
  • .github 目录
• 基于模版仓库建立新的项目
  • 设置仓库为模版仓库
  • 使用模版仓库
  • 后期工做
• 交流

背景

开源社区有不少工具能够帮助开发者快速生成一个我的项目，但有时候你可能会遇到如下问题：

1. 工具生成的项目过于复杂，不少东西都不必
2. 生成过程当中设置了不少问题，每次都回答一遍很繁琐
3. 生成项目后仍须要修修改改，加上本身喜欢的一些内容
4. 找不到彻底适用于本身的模版

或许你已经从零开始或基于相似 Yeoman 的工具开发了一个本身的脚手架，但其实 Github 建立模板仓库的功能就能够知足你的需求。

这个功能适合知足如下条件的项目模版：

项目模版彻底定制化，而非通用化。这意味着没法像 CLI 工具同样经过设置问题来替换模版中相应的内容，从而作到不一样喜爱的人也能经过选择来生成本身想要的项目。

因此，若是你常常建立我的项目，而且每次都和前几回架构差很少，那么经过这种方法来建立本身的模版是再简单不过了。

如何作到满意

在讲 Github 的模版仓库功能以前，咱们先来谈一谈建立一个模版仓库须要考虑哪些问题，才能使得这个仓库让本身满意。毕竟你须要从零开始建立一个仓库，才能在 Github 上将它设为模版仓库。

通常来讲，开发者老是会对本身的项目感到满意，即使之后学了新的知识发现原来很糟糕。这是由于建立项目时的所做所为已经达到了本身的现有水平，从而得到了知足感。

因此，咱们在创建项目的时候，应该经过对比当时一些知名的开源项目来创建满意度，而不是基于本身现有水平来创建。它们的高度更高，产生满意的情绪更难。可是一旦满意，那么你的项目高度也就上去了。

接下来，我会列举 9 个开源项目要考虑的工程化要素，而且给出一些建立项目模版时快速达到该工程化目标的技巧，但愿能给你们一些启示。

TypeScript

若是你准备建立的项目知足如下任一条件，那么你就该考虑使用 TypeScript 来编写你的项目了：

1. 从时间上看，是有可能中长期更新或者维护的项目
2. 从空间上看，项目不是很小，有必定复杂度
3. 从情感上看，想要引入类型系统让本身舒心，或者喜欢写类型和接口

Tips

1. 本地安装 typescript 后，可使用 npx tsc --init 来生成一份 tsconfig.json 文件。该文件列有 TypeScript 全部的配置，你只须要取消相应配置的注释就能够启用它了。这个配置最好放在项目模版里，免得每次都要复制粘贴。

2. 若是你的项目模版是 Node 相关的，别忘了在 package.json 中加入 @types/node。

编码规范

一个项目须要有统一的编程风格和规范，通常来讲，使用 EditorConfig 来规范编辑器的格式，使用 ESLint 来检查代码错误和规范编程风格。市面上最流行的 ESLint 规范应该是 Airbnb JavaScript Style Guide 和 JavaScript Standard Style 这两个了。

Tips

1. 若是你使用 VSCode，能够安装一个 EditorConfigGenerator 插件来快速生成一份 .editorconfig 文件。

2. 本地安装好 eslint 以后，可使用 npx eslint --init 来快速生成一份本身想要的 .eslintrc.js 的配置。

3. 若是你使用 TypeScript 语言和 VSCode 来开发，你或许还须要在项目模版根目录下新建一个 .vscode 目录，而且在该目录下新建一个 settings.json 文件，写下如下内容，以便启用 VSCode 中 ESLint 插件的自动修复功能：

   {
       "eslint.validate": [
           "javascript",
           "javascriptreact",
           {
               "language": "typescript",
               // 这个属性就表明要对 typescript 语言启用自动修复功能
               "autoFix": true
           }
       ]
   }
   复制代码

   配置好后，即可以在 VSCode 的命令面板中找到 ESLint: Fix all auto-fixable Problems 进行自动修复了：

   

测试框架

一个良好的开源项目必定是要有比较高的测试覆盖率的，因此选择一个测试框架来写测试代码相当重要。我比较喜欢 Jest，由于上手容易，一个包就能解决不少诉求，同时有大厂背书，比较适合我的开源项目。

关于 Jest 的一些核心配置能够阅读这篇文章

Tips

• 本地安装好 jest 以后，可使用 npx jest --init 来快速生成一份 jest.config.js 配置文件。

Commit 规范

优秀的开源项目每每都有规范、容易阅读的 Commit 信息，咱们能够借助一些工具来帮助咱们达到目的。主要是从如下两点入手：

1. 在写 Commit 信息时提醒如何填写关键信息，例如提交类型、涉及更改的文件等；

   为了实现这一点，咱们能够借助 husky 来指定 prepare-commit-msg 钩子触发时执行的命令，也就是在 git commit 运行后立马执行的命令。该命令实际执行的程序可使用 commitizen。在 package.json 中这样写：

   {
       // 其余配置......
       "husky": {
           "hooks": {
               "prepare-commit-msg": "exec < /dev/tty && git cz --hook || true"
           }
       }
       // 其余配置......
   }
   复制代码

   commitizen 就是一款提示你如何填写 Commit 的命令行工具，可经过 git cz 直接调用。它自己不包含 Commit 规范，须要另外安装一个规范库来搭配使用。比较流行的规范是 Angular 团队的 Commit 规范，对应的包是 cz-conventional-changelog。你须要在 package.json 中写下以下配置才能让 commitizen 使用这个规范：

   {
       // 其余配置......
       "config": {
           "commitizen": {
               "path": "./node_modules/cz-conventional-changelog"
           }
       }
       // 其余配置......
   }
   复制代码

2. 提交 Commit 信息时验证其是否符合 Commit 规范。

   要实现这一点，咱们一样要借助 husky，在 commit-msg 钩子这执行检验 Commit 的命令。负责这一命令的工具是 @commitlint/cli，它也不包含校验的规则，须要另外安装 @commitlint/config-conventional 来让 commitlint 明确是按 Angular 团队的规范来校验 Commit 信息。在 pakcage.json 这样写：

   {
       // 其余配置......
       "husky": {
           "hooks": {
               "prepare-commit-msg": "exec < /dev/tty && git cz --hook || true",
               // husky 新增的配置，运行 commitlint 命令
               "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
           }
       },
       // commitlint 配置
       "commitlint": {
           "extends": [
               // commitlint 校验的规范标准
               "@commitlint/config-conventional"
           ]
       }
       // 其余配置......
   }
   复制代码

上述两个内容配置好后，当你运行 git commit 的时候，会产生如下的效果：

CI / CD

优秀的开源项目都会有自动化测试，而在提交代码的时候必须经过测试才能合到主分支，这个测试过程就能够放到 CI 上来进行。另外，若是你的项目还涉及到构建、部署等，那就更须要 CI / CD 了。

对于在 Github 上开源的项目来讲，Github Actions 就是一个很是不错的选择。

Github Actions 首次使用须要用户去它的官网申请，申请好了之后，就会发现本身的全部仓库中都会有个 Actions 的选项卡，这里面就能看到该仓库 CI / CD 的状况。

因此，在你的项目或项目模版里，能够新建一个 .github 目录，而且在该目录下新建一个 workflows 目录，而后在这个目录下随便建一个 .yml 文件，通常叫 build.yml，由于在 README 的徽章里会使用这个名字，若是 CI / CD 经过的话，则这个徽章会显示绿色，而且文字是 build passing。

例如，若是你的项目须要跑一下测试，build.yml 里面就能这么写：

# 持续集成工做流
# 语法：https://help.github.com/cn/articles/workflow-syntax-for-github-actions

name: build

on: push

# 任务
jobs:
    # 测试任务
 test:
 name: test
        # 运行环境
 runs-on: ${{ matrix.os }}

        # 构建矩阵，让任务在如下平台和 Node 版本中都跑一遍
 strategy:
 matrix:
 os: [ubuntu-latest, windows-latest, macOS-latest]
 node: [6, 8, 10]

        # 运行步骤
 steps:
        # actions/checkout 为必须的，用于拉取代码到虚拟环境中
 - uses: actions/checkout@v1
        # actions/setup-node 非必须的，这里使用只是为了后续可使用各类版本的 node
 - uses: actions/setup-node@v1
 with:
 node-version: ${{ matrix.node }}
 - run: | npm i npm run test 复制代码

想要了解更多 Github Actions 的内容，能够直接查看官方的中文文档，写的挺详细的。

文档

良好的 README 文件可以使你的项目更容易理解和使用，多语言的 README 更会使你的项目大放异彩。通常 README.md 文件是英文文档，README.zh-CN.md 是中文文档。强烈建议新手按照 Standard Readme Style 规范来编写本身的文档，多写几遍，你就明白 README 该写些什么东西了。

CHANGELOG

几乎每个开源项目都会写 CHANGELOG，它和 README 同样重要。请注意，CHANGELOG 是写给将来的本身或参与项目的其余人看的，更是写给用户看的。因此这里就不推荐自动把 Commit 拼凑成 CHANGELOG 的工具了，除非你的 Commit 信息写的足够人性化，那么你却是能够用一用 conventional-changelog。

我更建议新手手动写 CHANGELOG，和 README 同样，CHANGELOG 在社区也有一套 keep a changelog 规范，它会教你如何把 CHANGELOG 写好。

协议

养成书写协议的习惯，从而对多数开源项目的版权有必定了解，也对本身将来的开源项目须要使用哪些协议有清晰的认识。通常来讲都是采用 MIT 协议，这是最为宽松的协议。若是你还不知道该使用什么协议，那么这个网站能够帮到你。

在你项目模版的 README 末尾，写上协议名称和仓库做者。另外再建立一个 LICENSE 文件，写明协议的详细信息。

.github 目录

若是你的项目是与他人合做或者但愿其余人来帮助改进，那么这些帮助在 Github 上协做的文档就能够放在 .github 目录下。常见的会放入如下文件：

1. COMMIT_CONVENTION.md：该文档是 Commit 规范的内容，帮助其余开发者知道项目须要如何 Commit
2. CONTRIBUTING.md：该文档是告诉其余开发者要怎么样对该项目进行贡献的
3. ISSUE_TEMPLATE.md：该文档是告诉提 issue 的用户如何写 issue 并提供 issue 模版
4. PULL_REQUEST_TEMPLATE.md：该文档是告诉提 PR 的用户如何写 PR 并提供 PR 模版

有了这些文件，会使你的项目更加友好。

基于模版仓库建立新的项目

如今你已经知道了建立一个项目或项目模版大概要考虑哪些工程化因素了，固然，工程化还远远不止这些，不一样类型的项目所须要的内容也不同。上述内容也仅刚恰好能知足我开发一个命令行工具模版仓库。不过，我已经能够基于这个初级模版仓库建立新的项目了。

设置仓库为模版仓库

1. 将建立好的仓库上传到 Github（切记不要把模版仓库的 package-lock.json 上传上去，但同时 .gitignore 不能忽略它，由于新项目须要上传上去）

2. 在 Github 仓库的 Settings 选项卡中勾选中 Template repository 一项

   

这样你的仓库就变成一个模版仓库了。

使用模版仓库

仓库被设置成模版仓库后，你就能在仓库的主页找到 Use this template 按钮：

点击此按钮就能够基于该模版仓库建立一个新的仓库了，试试看吧。

后期工做

新仓库被建立后，克隆下来，会有几个地方须要修改，能够在设计模版仓库时使用一些技巧并借助编辑器批量完成：

1. 新仓库的名称批量修改。设计模版仓库时凡是要修改为项目名称的地方都写上模版仓库的名称，而后在新项目中搜索它并所有替换成新仓库的名称。
2. package.json 的 description 要修改为对新仓库的描述。

交流

你们有兴趣能够关注一下个人博客，也能够关注个人公众号「前端拾贝」，以获取更多原创好文，并在讨论区进行交流。这些文章都是来自于平常开发中的总结，对理论和实践都比较有帮助：：