快来利用 Github 这个功能来创建让自己满意的项目模版吧

我承认我实在想不出更好的标题了,因为本文涉及到的内容比较宽泛。但我保证,本文会尽可能做到抛砖引玉的效果。不仅仅是创建项目模版,写项目的时候需要考虑的东西本文也适合。

本文主要会讲以下几个内容:

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

阅读过程中可以同时参考我写的一个模版仓库样例,如有常用 TypeScriptVSCode的读者,食用起来会更佳。

目录

背景

开源社区有很多工具可以帮助开发者快速生成一个个人项目,但有时候你可能会遇到以下问题:

  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 GuideJavaScript Standard Style这两个了。

Tips

  1. 如果你使用 VSCode,可以安装一个 EditorConfigGenerator插件来快速生成一份 .editorconfig文件。

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

  3. 如果你使用 TypeScript语言和 VSCode来开发,你或许还需要在项目模版根目录下新建一个 .vscode目录,并且在该目录下新建一个 settings.json文件,写下以下内容,以便启用 VSCodeESLint插件的自动修复功能:

    {
        "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.jsondescription要修改成对新仓库的描述。

交流

大家有兴趣可以关注一下我的博客,也可以关注我的公众号「前端拾贝」,以获取更多原创好文,并在讨论区进行交流。这些文章都是来自于日常开发中的总结,对理论和实践都比较有帮助::

原文链接:segmentfault.com

上一篇:grunt-modernizr
下一篇:Vue 2.x diff原理详解

相关推荐

  • 高效阅读Github源代码

    三种办法。如果你主要看前端项目的代码,直接看第三种。 1,用Chrome插件Octotree,左侧会出现树形结构,方便你浏览源代码。 (https://img.javascriptcn.com/6...

    2 年前
  • 链接和执行外部JavaScript文件托管在GitHub上

    AuthorProxy(https://stackoverflow.com/users/1763061/authorproxy)提出了一个问题:Link and execute external Ja...

    2 年前
  • 金三银四,前端同学快来补补React原理吧

    这是我几个月前写的文章,在前端面试中原理相关的问题是问的最多的,所以重新推荐下这几篇文章 深入学习一个框架最直接的方式,就是弄明白框架的原理。React无疑是一个非常值得学习其原理的框架,它设计简单...

    1 年前
  • 邀好友赢大奖!快来抽取你的 2019 新年上上签!

    还有不到一个星期,2019 年就将正式「官宣」。值此之际,七牛云特别推出【好运好礼】新年上上签活动~不仅有好运好彩头,还有超多惊喜好礼等你拿。天猫购物卡、七牛云产品优惠包、樱桃机械键盘、终极大奖 iP...

    1 年前
  • 详解vue父子模版嵌套案例

    这里是父子模版的调用 这里是针对于vue1.0,如果要学2.0,建议大家去看官方文档 vue2.0 :http://vuefe.cn/guide/(http://vuefe.cn/guide/) ...

    3 年前
  • 详解JavaScript对W3C DOM模版的支持情况

    本文档对象模型允许访问所有的文档内容和修改,由万维网联合会(W3C)规范。几乎所有的现代浏览器都支持这种模式。 在W3C DOM规范的大部分传统DOM的功能,而且还增加了新的重要的功能。

    3 年前
  • 详解 Github App 的玩法

    image(https://img.javascriptcn.com/8ee2bda1b962f5c4f8ece5c07608382e "image") 之前在使用 Github issues 搭建...

    1 年前
  • 用vue2.x版本+adminLTE开源框架 搭建后台应用模版

    1、创建工程 2、安装 jquery 并在build/webpack.base.conf.js中, 引入webpack 以及在当前文件下找到 module.exports 中 》re...

    1 年前
  • 用Flutter开发一个github客户端

    Gitme(https://flutterchina.club/app/gm.html) 是Flutter中文网https://flutterchina.club/(https://flutterc...

    2 年前
  • 理想中的Jenkins+Sonar+Github代码质量管理

    背景 前阵子老美的Audit要求各个开发组截图各自repository的Sonar Analysis Report,我跑去Sonarqube一看。。。好家伙!全是红灯,简直惨不忍睹 clipbo...

    2 年前

官方社区

扫码加入 JavaScript 社区