|
| 1 | +# 贡献指南 |
| 2 | + |
| 3 | +十分感谢您愿意贡献本项目. 在此之前请先阅读本指南, 本指南会从`cli`贡献与`pro套件`贡献两个方向展开. |
| 4 | + |
| 5 | +## 前置准备 |
| 6 | + |
| 7 | +### Clone仓库 |
| 8 | + |
| 9 | +- 点击 [TinyCLI](https://github.com/opentiny/tiny-cli) 代码仓库右上角的 Fork 按钮，将上游仓库 Fork 到个人仓库 |
| 10 | +- Clone 个人仓库到本地 |
| 11 | +- 在 Tiny CLI 根目录下运行 npm init, 安装依赖 |
| 12 | +- 运行 npm run dev，启动本地代码编译开发 |
| 13 | + |
| 14 | +```shell |
| 15 | +# username 为用户名，执行前请替换 |
| 16 | +git clone git@github.com:username/tiny-cli.git |
| 17 | +cd tiny-cli |
| 18 | +git remote add upstream git@github.com:opentiny/tiny-cli.git |
| 19 | +``` |
| 20 | + |
| 21 | +### 依赖安装 |
| 22 | + |
| 23 | +在 Tiny CLI 根目录下运行 `npm run init` 安装依赖。 |
| 24 | + |
| 25 | +## CLI 贡献 |
| 26 | + |
| 27 | +### 环境准备 |
| 28 | + |
| 29 | +```bash |
| 30 | +npm run dev |
| 31 | +``` |
| 32 | + |
| 33 | +执行上述命令后，出现 `Found 0 errors. Watching for file changes.` 字样则代表开发环境搭建成功。接下来我们需要进入开发阶段 |
| 34 | + |
| 35 | +### 命令开发 |
| 36 | + |
| 37 | +本章我们将会开发一个命令叫做 `health` 该命令将会输出操作系统、CPU架构、CPU核心数、内存总数(MB单位)。假设我们输入`tiny health`，控制台应该显示 |
| 38 | + |
| 39 | +``` |
| 40 | + Cpu: |
| 41 | + Intel(R) Core(TM) i5-4460 CPU @ 3.20GHz |
| 42 | + CpuTotal: 1 |
| 43 | +CpuKernalTotal: 4 |
| 44 | + Arch: x64 |
| 45 | + Platform: win32 |
| 46 | + Memory: 8129 MB |
| 47 | + FreeMemory: 6832 MB |
| 48 | + Time: 2024/9/27 |
| 49 | +``` |
| 50 | + |
| 51 | +左边是机器信息的名字，右边是数值。CPU因为只有一个所以只显示一个，如果有多个那么则显示多个。 |
| 52 | + |
| 53 | +首先请确保您运行了`npm run dev`。其次，请另开一个终端执行`npm run link`. 当出现`lerna success run Ran npm script 'link' in 1 package in 47.7s:`字样则表示`link`成功。后续操作不需要继续重复`link` |
| 54 | + |
| 55 | +接下来我们在`packages\cli\commands\src`下创建`health.ts`文件。并写入如下代码 |
| 56 | + |
| 57 | +```ts |
| 58 | +// packages\cli\commands\src\health.ts |
| 59 | +export default function(){} |
| 60 | +``` |
| 61 | + |
| 62 | +紧接着我们在`packages\cli\commands\src\index.ts`文件下导入health文件并导出。最终`packages\cli\commands\src\index.ts`文件应该如下所示 |
| 63 | + |
| 64 | +```ts |
| 65 | +// packages\cli\commands\src\index.ts |
| 66 | +/** |
| 67 | + * Copyright (c) 2022 - present Tiny CLI Authors. |
| 68 | + * Copyright (c) 2022 - present Huawei Cloud Computing Technologies Co., Ltd. |
| 69 | + * |
| 70 | + * Use of this source code is governed by an MIT-style license. |
| 71 | + * |
| 72 | + * THE OPEN SOURCE SOFTWARE IN THIS PRODUCT IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL, |
| 73 | + * BUT WITHOUT ANY WARRANTY, WITHOUT EVEN THE IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR |
| 74 | + * A PARTICULAR PURPOSE. SEE THE APPLICABLE LICENSES FOR MORE DETAILS. |
| 75 | + * |
| 76 | + */ |
| 77 | +import i from './i'; |
| 78 | +import clear from './clear'; |
| 79 | +import help from './help'; |
| 80 | +import init from './init'; |
| 81 | +import list from './list'; |
| 82 | +import locale from './locale'; |
| 83 | +import main from './main'; |
| 84 | +import update from './update'; |
| 85 | +import version from './version'; |
| 86 | +import install from './install'; |
| 87 | +import config from './config'; |
| 88 | +import health from './health'; |
| 89 | + |
| 90 | +export default { |
| 91 | + i, |
| 92 | + clear, |
| 93 | + help, |
| 94 | + init, |
| 95 | + list, |
| 96 | + locale, |
| 97 | + main, |
| 98 | + update, |
| 99 | + install, |
| 100 | + version, |
| 101 | + config, |
| 102 | + health |
| 103 | +}; |
| 104 | +``` |
| 105 | + |
| 106 | +保存后，在终端中运行`tiny health`命令，会发现控制台没有任何的输出。这是因为`health.ts`文件的默认导出是一个空函数，空函数执行自然不会有任何的输出。所以接下来我们要开始真正的开发了. |
| 107 | + |
| 108 | +将下列代码复制到`packages\cli\commands\src\health.ts`下并保存。之后运行`tiny health`命令会发现，控制台输出了当前机器的一些信息 |
| 109 | + |
| 110 | +```ts |
| 111 | +// packages\cli\commands\src\health.ts |
| 112 | +import { cpus, arch, platform, totalmem, freemem } from 'os' |
| 113 | +import { stdout } from 'process'; |
| 114 | +const formatTitle = (title: string) => `${title[0].toUpperCase()}${title.slice(1)}` |
| 115 | +const toMB = (size: number) => Math.floor(size / 1024 / 1024) |
| 116 | +const formatMemoryString = (size: number) => `${size} MB` |
| 117 | +export default async function () { |
| 118 | + const result = { |
| 119 | + cpu: [] as string[], |
| 120 | + cpuTotal: 0, |
| 121 | + cpuKernalTotal: 0, |
| 122 | + arch: arch(), |
| 123 | + platform: platform(), |
| 124 | + memory: formatMemoryString(toMB(totalmem())), |
| 125 | + freeMemory: formatMemoryString(toMB(totalmem()) - toMB(freemem())) |
| 126 | + }; |
| 127 | + const cpuInfos = cpus() |
| 128 | + result.cpu = Array.from(new Set(cpuInfos.map(cpuInfo => cpuInfo.model))); |
| 129 | + result.cpuTotal = result.cpu.length; |
| 130 | + result.cpuKernalTotal = cpuInfos.length; |
| 131 | + const entries = Object.entries(result) |
| 132 | + let maxLenKey = entries[0][0] |
| 133 | + let maxValueKey = 0; |
| 134 | + for (let i = 1; i < entries.length; i++) { |
| 135 | + if (entries[i][0].length > maxLenKey.length) { |
| 136 | + maxLenKey = entries[i][0]; |
| 137 | + } |
| 138 | + if (entries[i][1] instanceof Array) { |
| 139 | + continue; |
| 140 | + } |
| 141 | + if (entries[i][1].toString().length > maxValueKey) { |
| 142 | + maxValueKey = entries[i][1].toString().length; |
| 143 | + } |
| 144 | + } |
| 145 | + for (const [key, value] of entries) { |
| 146 | + stdout.write(formatTitle(key).padStart(maxLenKey.length,) + ': ' + (value instanceof Array ? '\n' : '')); |
| 147 | + if (value instanceof Array) { |
| 148 | + value.forEach(val => { |
| 149 | + stdout.write(val.padStart(maxLenKey.length + 2 + val.length) + '\n') |
| 150 | + }) |
| 151 | + } else { |
| 152 | + stdout.write(value.toString() + '\n') |
| 153 | + } |
| 154 | + } |
| 155 | +} |
| 156 | + |
| 157 | +``` |
| 158 | + |
| 159 | +#### 这段代码做了什么事？ |
| 160 | + |
| 161 | +这段代码主要使用`os`包来获取机器信息，而后通过stdout来进行输出。之所以使用stdout主要是可以更加灵活的进行输出，实际上使用`console.log`效果也是一样的 |
| 162 | + |
| 163 | +## `tiny-toolkit-pro` 套件贡献 |
| 164 | + |
| 165 | +### 第一节、目录结构 |
| 166 | + |
| 167 | +``` |
| 168 | +packages |
| 169 | + toolkits |
| 170 | + pro |
| 171 | + src |
| 172 | + lib |
| 173 | + build.ts # 对应的是 tiny pro build |
| 174 | + help.ts # 对应的是 tiny pro help |
| 175 | + init.ts # 对应的是 tiny pro init |
| 176 | + interface.ts |
| 177 | + start.ts # 对应的是 tiny pro start |
| 178 | + utils.ts |
| 179 | + template |
| 180 | + server # 后端模板 * 本章只涉及nestjs后端 |
| 181 | + tinyng # ng前端模板 |
| 182 | + tinyvue # vue3前端模板 * 本章只涉及Vue前端 |
| 183 | +``` |
| 184 | + |
| 185 | +### 第二节、贡献套件命令 |
| 186 | + |
| 187 | +套件命令对应的文件请参考上一节 `目录结构`. 当修改了套件命令后，贡献者**必须**发布一个私有的套件包。并设置环境变量`TINY_SCOPE`为您的`npm`名称 |
| 188 | + |
| 189 | +### 第三节、发布私有套件包 |
| 190 | + |
| 191 | +发布私有套件包前，我们假设你拥有npm账号且已经完成了[前置准备](#前置准备)，且已经登陆。如果没有登陆请参考[npm登录](https://docs.npmjs.com/cli/v10/commands/npm-login?v=true)。 |
| 192 | + |
| 193 | +1. 替换`packages\toolkits\pro\package.json`中`@opentiny/tiny-toolkit-pro` 为 `@<您的npm名称>/tiny-toolkit-pro` |
| 194 | +2. 在`packages\toolkits\pro`下运行`npm publish --access=public` |
| 195 | +3. 修改环境变量`TINY_SCOPE=<第一步骤中您填写的私有scope>` |
| 196 | +4. 安装`npm i -g @opentiny/cli` (如果您安装完成或link了开发产物可忽略该步骤) |
| 197 | +5. `rm -rf ~/.tiny` |
| 198 | +6. **新启用一个bash**并执行`tiny init pro` |
| 199 | + |
| 200 | +当出现`[core-module]: 本地尚未安装 @<您的npm名称>/tiny-toolkit-pro ,正在执行自动安装...`后则代表私有包发布成功 |
| 201 | + |
| 202 | + |
| 203 | +### 贡献套件 |
| 204 | + |
| 205 | +您可以使用IDE打开`packages\toolkits\pro\templates`，进入对应的技术栈后安装依赖，之后跟随开发指南进行开发 |
| 206 | + |
| 207 | +- [前端二次开发指南](./tiny-pro-front-dev-guideline.md) |
| 208 | +- [后端二次开发指南](./tiny-pro-backend-dev-guideline.md) |
| 209 | + |
| 210 | +#### 如何调试 |
| 211 | + |
| 212 | +- [ ] nestJs后端 |
| 213 | + - 源码位置: `packages\toolkits\pro\templates\server\nestJs` |
| 214 | + - 安装nestJs依赖: `npm i` |
| 215 | + - 启动nestJs本地调试: `npm run start` |
| 216 | + - [启动MySQL数据库](https://dev.mysql.com/doc/refman/8.4/en/tutorial.html) |
| 217 | + - [启动Redis](https://redis.io/docs/latest/get-started/) |
| 218 | +- [ ] vue3前端 |
| 219 | + - 源码位置: `packages\toolkits\pro\templates\tinyvue` |
| 220 | + - 安装nestJs依赖: `npm i` |
| 221 | + - 启动nestJs本地调试: `npm run start`(默认vite启动) |
| 222 | + - webpack启动: `npm run dev:wp` |
| 223 | + - rspack启动: `npm run dev:rp` |
| 224 | + - [成功启动页面](./images/tiny-pro-show.png) |
| 225 | + |
| 226 | +## 遇到困难? |
| 227 | + |
| 228 | +加官方小助手微信 opentiny-official，加入技术交流群 |
0 commit comments