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

2019-10-13 admin

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

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

  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 进行自动修复了:

    eslint auto fix

测试框架

一个良好的开源项目一定是要有比较高的测试覆盖率的,所以选择一个测试框架来写测试代码至关重要。我比较喜欢 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 的时候,会产生以下的效果:

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 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 一项

    template repository

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

使用模版仓库

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

use this template

点击此按钮就可以基于该模版仓库创建一个新的仓库了,试试看吧。

后期工作

新仓库被创建后,克隆下来,会有几个地方需要修改,可以在设计模版仓库时使用一些技巧并借助编辑器批量完成:

  1. 新仓库的名称批量修改。设计模版仓库时凡是要修改成项目名称的地方都写上模版仓库的名称,然后在新项目中搜索它并全部替换成新仓库的名称。
  2. package.jsondescription 要修改成对新仓库的描述。

交流

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

微信公众号二维码

[转载]原文链接:https://segmentfault.com/a/1190000020669046

本站文章除注明转载外,均为本站原创或编译。欢迎任何形式的转载,但请务必注明出处。

转载请注明:文章转载自 JavaScript中文网 [https://www.javascriptcn.com]

本文地址:https://www.javascriptcn.com/read-77248.html

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

相关文章
JS生成一维码(条形码)功能示例
本文实例讲述了JS生成一维码(条形码)功能的方法。分享给大家供大家参考,具体如下: 1、js代码: (function() { if (!exports) var exports = window; var BARS = [212...
2017-03-01
JS中Select下拉列表类(支持输入模糊查询)功能
下面给大家分享一段代码关于select下拉列表类支持输入模糊查询功能的实现代码,具体代码如下所示: &lt;span style=&quot;font-size:14px;&quot;&gt; &lt;HTML&gt; &lt...
2017-03-06
搜狐发力html5让用户更爽,自媒体人更嗨
曾经有资深互联网分析师说过”2015年,新闻综合类 APP 如果还没有大量的个性化阅读功能,将被淘汰出局。”枣哥非常同意此观点,移动互联网时代已经席卷全球,移动互联网代表的就是个性张扬的时代,在互联网圈说道个性张扬首先想到的是搜狐老板张朝阳...
2015-11-12
百度新功能【特效搜索】演示 惊呆了小伙伴
百度搜索最近又出新玩意新功能了,可能你还没有发现,名为【百度特效搜索】已经默默上线了,有什么效果呢? 在百度搜索中根据用户搜索的关键词来出发某些动作,例如笔者搜索“打雷”关键字,在搜索结果中你会听到有打雷声, 黑洞,闪烁、翻转、跳跃,打雷,...
2015-11-12
游戏机遇到来 非主流HTML5能否成器?
2014年第四季度以来,有60%的游戏行业从业者已经投入或准备投入开发HTML5为基础的游戏,并对其前景表示乐观的态度。   对HTML 5这项诞生于2008年的标准来说,其正在经历最好的时代。 游戏机遇到来 非主流HTML5能否成器?  ...
2015-11-12
VuePress 快速踩坑
最近有个开源项目非常火,那就是尤小右开发的 VuePress,VuePress 可以让您非常方便的在 Markdown 文档中编写 Vue 代码,并且 VuePress 对编译后的 HTML 文件做了一些针对搜索引擎的优化。另外 VuePr...
2018-04-27
HTML5:未来不可阻挡的力量
HTML5像是互联网行业扔下的一颗炸弹,有些人还未反应过来,原先专注的领域也许就将面临彻底的革新。比如像前几年疯狂甚至有点野蛮成长的App。虽然HTML5从出现到去年标准尘埃落定,一直在争议中曲折发展,但是各种H5页面的推广以及H5小游戏在...
2015-11-12
Angular 6 正式发布,新功能详解
作者|Stephen Fluin编译|覃云今天,Angular 6.0.0 正式发布,新版本重点关注工具链以及工具链在 Angular 中的运行速度问题。 这次更新还包括框架包(@angular/core、@angular/common、@...
2018-05-05
微信火了HTML5,技术革新才是未来
Html5小游戏自从诞生以来,以其玩法简单、内容娱乐等特点,而深受玩家的欢迎。就像音乐领域的《小苹果》和《最炫名族风》一样,Html5小游戏也曾经有多款神作,在微信朋友圈如病毒式疯传。 微信让H5火了 去年,H5游戏“围住神经猫”上线微信朋...
2015-11-12
javascript中文网开通评论功能
javascript中文网开通评论功能啦,欢迎大家留言评论 ...
2015-11-12
回到顶部