配置git的用户名、公司邮箱以及文件换行符

  1. git config --global user.email "你的公司用户名@xiaomi.com"
  2. git config --global user.name "你的邮箱名前缀"
  3. git config --global core.autocrlf input
  4. //验证命令
  5. git config --global --list

Git代码提交规范：

推荐使用：脚手架创建默认集成commit规范检查的项目
不使用脚手架的操作步骤：

插件安装

  • 安装 @commitlint/cli 

    1. npm install --save-dev @commitlint/cli

    插件配置

  • 在项目根目录下创建 commitlintrc.js 文件 

    1. touch .commitlintrc.js

  • 在 commitlintrc.js 文件中填充如下内容

    1. module.exports = {
    2. rules: {
    3.   'type-enum': [
    4.     2,
    5.     'always',
    6.     [
    7.       'feat', // 新增功能（feature）
    8.       'fix', // 修补 bug
    9.       'refactor', // 重构某功能（不是 feat, 不是 fix）
    10.       'style', // 代码格式化（比如空格、缩进、末尾分号等）
    11.       'docs', // 文档修改（比如 README.md）
    12.       'test', // 增加测试用例等
    13.       'perf', // 性能优化
    14.       'revert', // 回滚某个更早之前的提交
    15.       'chore' // 琐事，如移除 log、无用代码，修改翻译文案，依赖包升级，ci 构建配置更改
    16.     ]
    17.   ],
    18.   'subject-full-stop': [2, 'never', '.'], // subject 结尾不加'.'
    19.   'type-case': [2, 'always', 'lowerCase'], // type 小写
    20.   'type-empty': [2, 'never'] // type 不为空
    21. }
    22. }

    提交前检查

  • 安装 husky 

    1. npm install -D husky

  • 配置 package.json 进行代码提交检查集成 

    1. "husky": {
    2. "hooks": {
    3.   "commit-msg": "commitlint -e $HUSKY_GIT_PARAMS"
    4. }
    5. }

    配置完成之后，提交所写的 commit 内容如果不符合规范，则无法进行提交代码。

处理合并冲突

  • 确保检查过并处理到项目内所有的代码冲突
  • 合并冲突存在异议，建议找相关开发同学一起处理冲突

  • 合并冲突无异议，自行担保可直接处理

    Git代码分支规范

    一、依据部门统一规范执行

  • 依据代码分支规范（试行）执行

  • test 分支不能合并到 master 和 RELEASE
  • 所有开发变更必须限制在开发分支，不能直接在 test 和 master 等上进行开发提交

二、开发分支基本格式

  1. [type]/[name][-creator?]
  • type ：说明分支类型，表示该分支所要做事情的类型，采用如下枚举类型：
    • feature 功能
    • hotfix 小改动 或 bugfix
  • name ：表示该分支所要做的事情，采用 kebab-case 命名规范：全部小写，多个单词使用单个短横线(-)拼接
    • 对于 feature，内容根据添加的实际功能、迭代定义命名
    • 对于 hotfix， 内容可以使用当前日期作为名称命名
  • creator? ：可选，表示创建人、分支创建人的标识

Good✨
feature/search-zs1 表示 zs1 添加搜索功能
hotfix/160727-zs1 表示 zs1 在 2016 年 7 月 27 号打补丁
creator 为可选字段，比较适用于大型多人协作的项目开发维护：
1. 避免多人并行开发分支命名冲突
2. 方便分支检索和管理

三、定期清理远程分支

  • 在项目的 gitlab 首页中的「Repository」-「Branches」界面搜索自己的分支
  • 根据分支最后的更新日期，删除无用分支（标有 MERGED ）即可

  • 除重要分支或长期维护分支，其他分支建议每月清理一次，保留最近一个月的分支即可

    Git 工作流执行规范

    GitHub-flow

    含义：只存在一个master分支，所有开发者都基于master分支建立分支进行开发

  • GitHub-flow 工作流相对简单，且与现有大部分项目使用流程一致，适合多人或持续发布项目

  • 目前除执行 Git-flow 和部分特殊情况的项目，都需要执行 GitHub-flow 工作流

    GitHub-flow 注意事项

  • GitHub-flow 要求开始开发前要 fork 项目到自己的仓库。而在 gitlab 开发，所有人都在同一个项目下进行，不需要对项目进行 fork。

  • GitHub 上的 PullRequest 在 gitlab 上叫 MergeRequest，两者功能类似。

image.png

Git-flow

  • Git-flow 工作流相对比较复杂，分支的每步操作需要成员完全清楚当前的流程和后台会进行的操作，并需要严格按照规范操作
  • 但使用 Git-flow 可以最大程度保证项目安全、有节奏的完成发布和管理

  • 因此 Git-flow 适合有节奏按版本发布的项目

    Git-flow 注意事项

    老式的分支结构：层次递进地进行分支划分，将每个分支的具体操作划分好后，在特定的分支内进行修改代码

  • 由于项目需要在 gitlab 上进行合并 master 的操作，最后往 master 合并的阶段不能采用 Git-flow 的合并命令，而需要把当前分支手工 push 到远端，并在 gitlab 界面上提交 MergeRequest。

  • Hotfix 不能用 Git-flow 的 finish 命令直接结束，需要 push 到远程走 MergeRequest 进行合并，同时进行 CodeReview。

Git相关规范 - 图2

PR/MR规范

正常来说推荐用脚手架解决这种问题
不能使用脚手架的操作步骤：

使用标准的 MR 模板

  • 创建 gitlab 模板文件 .gitlab/merge_request_templates/MergeRequest.md
  • 粘贴如下内容到该文件

> 需求链接 wiki: 无 ### 本次 MR 做了什么 - 1. ### 本次 MR 是否进行了重大改版（比如升级 react 版本等造成的写法上的不兼容） - 无 ### 本次 MR 需要附加的信息（比如变更前后图） - 无

  • 并将代码合到项目主分支（默认主分支为master）推送到远程

参考：https://micode.be.xiaomi.com/help/user/project/description_templates

创建合格的 MR

  • 确保所有变动都提交到了当前开发分支，并提交推送到远程
  • 确保 MR 的内容要尽可能细致到一个类型（参见：代码提交规范（试行）中的 commit 类型）
  • 在 Gitlab 平台上手动创建 MR，选择对应的模板，按照格式清晰的描述本次 MR 涉及到的内容
  • 指定 CR 的主负责人（也可以是自己），提交 MR 完成创建

合并代码

  • 需要有至少一位其他同学进行交叉 Review代码
  • 直到 CR 中所有的疑问或批注解决或者有结论之后，才允许合并代码

  • 一般情况下，不建议自己合并自己的代码到保护分支

    README书写规范

    项目介绍

  • 一个顾名思义的项目名称

  • 简短的项目简述，用来介绍项目是干什么的，属于哪条业务线，有哪些重要的功能
  • 一些技术点，简单介绍项目所采用的重要技术点
  • 系统的访问方式，简单介绍如何访问该项目对应的系统，比如：对于一个 web 项目，我们可以列举下测试、预发布、线上环境对应的域名地址

项目资料

  • 当前项目基本成员及其角色
  • 项目文档，建议直接将项目资料链接地址贴在这里然后简短说明下即可，其中内容可能包括如下：
    • 项目的代码仓库地址
    • 项目的产品文档地址
    • 项目的视觉稿地址
    • 项目的接口文档地址

对于项目文档，建议由产品或项目负责人在飞书文档中创建项目文件夹，包括产品文档、设计稿、技术方案文档、UI走查以及 bug 列表文档等全部囊括在里面，由项目内所有成员共同维护。

环境配置

一般是我们需要的一些运行环境安装和配置，比如如下几种场景：

  • 因为项目历史原因，需要基于 Node 的某个特定版本
  • 小程序开发，需要提前安装小米办公 IDE 工具
  • 为了调试方便，本地开发需要安装 switchy omega 插件，设置浏览器代理

注意：这里需要详细说明具体环境如何安装和配置，如何接洽到项目中。

开发调试

说明我们怎么通过命令快速地开启本地开发和调试，如下是常见的 web 项目启动方式：
# 安装依赖 npm install # 本地开发，将启动 http://localhost:8088 npm run start # 本地构建 npm run build

部署发布

主要介绍项目如何进行部署发布，顺利完成上线，比如：执行 ./tag.sh 脚本触发 CI 自动化部署。
如果有用到一些发布平台，最好贴上该项目不同环境的发布地址和发布方式，减少我们发布的时间成本。

开发规范

对于开发规范，可能包含分支命名，代码风格等各种规范，默认来讲，说明下“本项目遵循大前端通用技术规范”即可。当然，如果有些额外的规范补充，也可在此申明。

目录结构

通过 tree 的形式展示基本的目录结构，并注以每个目录相关的功能说明。

其它

以上几点基本上已经包含了维护一个项目所需要的基本的重要的信息，如果有其他需要补充（比如：技术方案、TODOLIST 等），可以继续往下添加序号和内容。