# guide

**Repository Path**: gitee-frontend/guide

## Basic Information

- **Project Name**: guide
- **Description**: 码云前端开发规范
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2020-04-30
- **Last Updated**: 2023-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 码云前端规范

## 介绍

本文档为码云前端规范文档，覆盖所有码云前端项目，旨在提高前端项目的团队协作效率和可维护性。

## 准备

在开发新页面或新功能前，应该根据复杂度、扩展性、用途等因素规划仓库，然后在[码云前端组](https://gitee.com/gitee-frontend)名下新建仓库并在新仓库中进行开发。从零开始搭建一个前端项目比较麻烦，你可以基于[Vue 仓库模板](https://gitee.com/gitee-frontend/gitee-vue-repo-template)来搭建项目。

## 开发

目标仓库：

```bash
# 克隆本仓库
git clone git@gitee.com:gitee-frontend/目标仓库.git

# 进入仓库目录
cd 目标仓库名

# 安装依赖
npm install

# 将当前仓库链接到全局 node_modules 目录里
npm link

# 开始构建资源（development 模式）
npm run dev
```

主仓库：

```bash
# 将全局 node_modules 目录中的目标仓库链接链接到当前 node_moudles 目录中
npm link 目标仓库

# 构建资源（development 模式），以将目标仓库的资源复制到主仓库中
npm run dev:main
```

如果项目已提供 dev-server 支持，则只需在这个项目中运行 deve-server，然后将主仓库的 `config.webpack.dev_server.enabled` 配置项改为 `true` 并重启服务器即可。

## 发布

### 公开包的发布方法

如果需要将项目作为依赖包发布到 npm 包源，则需要满足以下条件：

- 已在 [npmjs.org](http://npmjs.org/) 上注册了账号
- 账号已经加入 gitee 组织，且有权限管理目标包
- 已用 `npm login` 命令登录了这个账号
- 依赖的 gitee-vendor-dll 包和主仓库中的一致
- 测试没问题

之后在命令行中运行：

``` bash
# 创建 beta 预发行版
npm run release-beta

# 发布测试版
npm publish --tag=beta

# 创建正式发行版
npm run release

# 发布正式版
npm publish
```

主仓库：

```bash
# 安装刚刚发布的测试版
npm install 目标包@beta

# 或者安装最新正式版
npm install 目标包@latest
```

### 私有包的发布方法

私有包的构建产物托管在 git 仓库中，发布就是把本地构建好资源推送到远程 gt 仓库。

```bash
# 更新版本号，构建资源
npm version 版本号 -m "chore(release): 版本号"

# 发布
git push origin master --tags
```

主仓库使用以下命令安装：

```
npm install git+https://账号:密码@gitee.com/gitee-frontend/目标仓库名.git#v版本号
```

## 编码规范

为什么需要编码规范？有什么意义？按自己的风格来写代码不爽吗？这种问题请自行搜索查阅相关资料。

### JavaScript

遵循码云前端的 [ESLint](https://gitee.com/mayun-team/eslint-config-gitee) 即可。

### CSS

在遵循 stylelint 的要求的前提下，还需要遵循以下规范：

- css 代码应该根据作用范围（页面、组件）拆分到独立的 scss 文件中
- 采用 BEM 命名风格

### Git Commit Message

遵循 [commitlint](https://github.com/conventional-changelog/commitlint) 的规范。该规范下的提交信息适合生成更新日志。

## 开发流程

1. 基于 master 创建一个新分支，然后在该分支上开发
1. 开发完后，向 master 分支提交 PR
1. 经管理员审查通过后合并此仓库的 PR 到 master
1. 管理员打包发布测试版本，版本号遵循[语义化版本控制规范](https://semver.org/lang/zh-CN/)，版本号格式为：`1.x.x-beta.x`，如果当天有多次更新，则应该只递增 beta 后面的编号
1. 在主仓库中安装这一测试版本，本地测试无问题后再更新到 PR 上
1. 如果测试版本还存在问题，需要继续修改，请重复上述流程
1. 数天之后如果一切正常，则由管理员将版本号更新为正式版

如果此次改动较大，需要花较多的时间测试，或依赖主仓库的后端新功能以及相关样式文件，必须与后端一同更新上线，则根据包的可见性，将下面对应的流程插入到第 2 步后。

### 公开包的开发流程

公开包使用 npm 包源，使用 `npm publish` 发版。

1. 使用 `npm version 版本号 -m "chore(release): 版本号` 发布 PR 专属版，格式为：`当前主版本-pr编号.子版本`，例如：`0.1.0-pr5.0`
1. 使用 `npm publish --tag=pr` 命令发布该版本到 npm 包源
1. 在主仓库中安装此版本
1. 按主仓库的开发流程提交 PR
1. 主仓库的 PR 审查和测试是否通过？
    - 是，进入下一步
    - 否
        1. 删除上次用 `npm version` 生成的提交
        1. 递增 PR 专属版本后面的子版本号，例如当前是 `0.1.0-pr5.0`，递增后则为 `0.1.0-pr5.1`
        1. 从上级步骤的第一步重新开始

### 私有包的开发流程

私有包使用 git 仓库托管，使用 `git tag v版本号` 和 `git push` 发版。

1. 使用 `npm version 版本号 -m "chore(release): 版本号` 发布 PR 专属版，格式为：`当前主版本-pr编号.子版本`，例如：`0.1.0-pr5.0`
1. 推送提交到仓库
1. 在主仓库安装此版本，命令格式为：`npm install "git+https://账号:密码@gitee.com/gitee-frontend/仓库名.git#v版本号"`
1. 按主仓库的开发流程提交 PR
1. 主仓库的 PR 审查和测试是否通过？
    - 是，进入下一步
    - 否
        1. 删除上次用 `npm version` 生成的提交
        1. 递增 PR 专属版本后面的子版本号，例如当前是 `0.1.0-pr5.0`，递增后则为 `0.1.0-pr5.1`
        1. 从上级步骤的第一步重新开始