ice/CONTRIBUTING.md

# 参与贡献

## 环境准备

1. 保证 Node.js 版本是 Node.js 14 以上。推荐安装 Node.js 16+ 版本，会大大提升本地调试速度
2. ice.js 仓库是 `monorepo`，并使用 `pnpm workspace`。因此需要安装 [pnpm](https://pnpm.io/) 包管理工具
3. 在项目根目录下执行 `pnpm run setup` 后会安装依赖和编译代码

> 如果在安装 puppeteer 的时候过慢，可以参考此 [issue](https://github.com/puppeteer/puppeteer/issues/6833#issuecomment-863488626) 进行配置 chromium 缓存。

## 目录说明

```markdown
ice-next
├── examples            # 存档各种示例代码
├── packages            # 存放 npm 包
|  ├── bundles          # 依赖预编译，锁定框架三方依赖版本，框架中的依赖需要从此包导入模块
|  ├── ice              # 工程代码，包括创建 service、构建任务、Webpack 和 esbuild 的打包编译逻辑等
|  ├── plugin-auth      # Auth 插件
|  ├── route-manifest   # 根据约定式路由生成路由配置
|  ├── runtime          # 运行时代码，包括 Client/Server 入口、Document、路由组件等
|  ├── types            # 公共 TS 依赖
|  └── webpack-config   # 存放 Webpack 默认的配置项
├── scripts             # 执行脚本
├── tests               # 测试用例
|  ├── integration
|  └── utils
└── website             # ice.js 官方文档
```

补充说明：

1. `packages` 目录下以 `plugin-xxx` 命名的都是插件包，插件的开发规范可以参考[文档]()
2. `packages/types` 是用于存放公共的 TS 类型声明，以在其他 `package` 中进行复用

## 调试

### 启动 watch 命令

此命令用于监听 `packages` 目录下代码变更，并增量编译代码。

```bash
pnpm watch
```

### 跑 example

`examples` 目录下存放了各种用于测试的 demo，并且自动 Link 到 `packages` 目录下的代码。只需执行以下命令即可开始调试：

```bash
# 进入某个 example
$ cd examples/basic-project
# 调试 example
$ pnpm start
```

`packages` 目录下的 `npm` 包在进行代码编译时会生成 `SourceMap`，结合 IDE 可以很方便进行断点调试。以 VS  Code 为例：

1. 选择 `JavaScript Debug Terminal` 进入 Debug 模式：
![image](https://user-images.githubusercontent.com/44047106/172011203-8b3b4016-8f7b-4743-bbef-30672ab04b03.png)

2. 进入某个 `example` 目录并执行 `pnpm start` 开始调试

3. 在某一行设置一个断点，当代码执行到此行时，将会停止执行并可查看各个变量的值
![image](https://user-images.githubusercontent.com/44047106/172013483-028d0fa8-8634-46fe-bbb6-1b28b39b8ce1.png)

## 测试

ice.js 使用 [vitest](https://vitest.dev/) 进行单元测试和集成测试。执行以下命令可快速运行项目中的测试用例：

```bash
# 执行一次测试并生成代码覆盖率
$ pnpm test
# 启用 Test Watch 模式
$ pnpm test:watch
# 只跑部分测试用例
$ pnpm test basic-project.test.ts
```

## 文档

ice.js 的文档使用了 [docusaurus](https://docusaurus.io/) 进行搭建。执行以下命令即可开始文档的开发：

```bash
# 进入到 website 目录
$ cd websites
# 安装依赖
$ yarn install
# 本地预览
$ yarn start 
```

## 发布

```bash
# 发布 alpha 版本
$ pnpm publish:alpha
# 发布 beta 版本
$ pnpm publish:beta
```