From 2de51d28f76897a29602e77fb5d93dbbbacbb044 Mon Sep 17 00:00:00 2001 From: zyl <495162889@qq.com> Date: Thu, 17 Jan 2019 01:29:01 +0800 Subject: [PATCH] add docs (#2) * docs: update site --- docs/.vuepress/config.js | 22 ++- docs/README.md | 6 + docs/archive/integrate-with-gitlab-ci.md | 3 - .../archive/integrate-with-gitlab-ci.zh-CN.md | 3 - docs/guide/integrate-with-gitlab-ci.md | 25 ++++ .../integrate-with-jenkins.md | 4 +- docs/{archive => guide}/jenkins-android.md | 0 docs/{archive => guide}/jenkins-ios.md | 0 docs/{archive => guide}/jenkins-web.md | 0 docs/guide/reliable-cli.md | 138 +++++++++++++++++ .../reliable-web-deploy.md} | 5 +- docs/zh/README.md | 6 + docs/zh/guide/integrate-with-gitlab-ci.md | 23 +++ .../guide/integrate-with-jenkins.md} | 2 +- .../guide/jenkins-android.md} | 0 .../guide/jenkins-ios.md} | 0 .../guide/jenkins-web.md} | 0 docs/zh/guide/reliable-cli.md | 140 ++++++++++++++++++ .../guide/reliable-web-deploy.md} | 7 +- 19 files changed, 363 insertions(+), 21 deletions(-) delete mode 100644 docs/archive/integrate-with-gitlab-ci.md delete mode 100644 docs/archive/integrate-with-gitlab-ci.zh-CN.md create mode 100644 docs/guide/integrate-with-gitlab-ci.md rename docs/{archive => guide}/integrate-with-jenkins.md (96%) rename docs/{archive => guide}/jenkins-android.md (100%) rename docs/{archive => guide}/jenkins-ios.md (100%) rename docs/{archive => guide}/jenkins-web.md (100%) create mode 100644 docs/guide/reliable-cli.md rename docs/{archive/marmot-web-deploy.md => guide/reliable-web-deploy.md} (91%) create mode 100644 docs/zh/guide/integrate-with-gitlab-ci.md rename docs/{archive/integrate-with-jenkins.zh-CN.md => zh/guide/integrate-with-jenkins.md} (98%) rename docs/{archive/jenkins-android.zh-CN.md => zh/guide/jenkins-android.md} (100%) rename docs/{archive/jenkins-ios.zh-CN.md => zh/guide/jenkins-ios.md} (100%) rename docs/{archive/jenkins-web.zh-CN.md => zh/guide/jenkins-web.md} (100%) create mode 100644 docs/zh/guide/reliable-cli.md rename docs/{archive/marmot-web-deploy.zh-CN.md => zh/guide/reliable-web-deploy.md} (90%) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index eb58f19..110a768 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -68,7 +68,7 @@ module.exports = { macacaEcosystem.en, ], sidebar: { - '/guide/': genSidebarConfig('Guide', 'Usage', 'Advanced'), + '/guide/': genSidebarConfig(['Guide', 'CI/CD', 'Community']), }, }, '/zh/': { @@ -90,20 +90,32 @@ module.exports = { macacaEcosystem.zh, ], sidebar: { - '/zh/guide/': genSidebarConfig('指南'), + '/zh/guide/': genSidebarConfig(['使用指南', '持续集成', '社区支持']), }, }, }, }, }; -function genSidebarConfig(guide) { +function genSidebarConfig(arr) { return [ { - title: guide, + title: arr[0], collapsable: false, children: [ - '', + 'reliable-cli', + 'reliable-web-deploy', + ], + }, + { + title: arr[1], + collapsable: false, + children: [ + 'integrate-with-jenkins', + 'jenkins-web', + 'jenkins-ios', + 'jenkins-android', + 'integrate-with-gitlab-ci', ], }, ]; diff --git a/docs/README.md b/docs/README.md index e249bca..5991447 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,3 +20,9 @@ Reliable is suitable for working with existing R&D processes in the continuous i ::: ![](https://wx3.sinaimg.cn/large/6d308bd9ly1fz3wii2wqsj21bh0u0qij.jpg) + +::: tip Deploy +Reliable supports one-click deployment, quickly has your own test management platform. +::: + +![](http://ww2.sinaimg.cn/large/6d308bd9gw1f5scrp1p4rj20rs0gatbj.jpg) diff --git a/docs/archive/integrate-with-gitlab-ci.md b/docs/archive/integrate-with-gitlab-ci.md deleted file mode 100644 index c8074fb..0000000 --- a/docs/archive/integrate-with-gitlab-ci.md +++ /dev/null @@ -1,3 +0,0 @@ -# Integrate With Gitlab CI - ---- diff --git a/docs/archive/integrate-with-gitlab-ci.zh-CN.md b/docs/archive/integrate-with-gitlab-ci.zh-CN.md deleted file mode 100644 index 9147f58..0000000 --- a/docs/archive/integrate-with-gitlab-ci.zh-CN.md +++ /dev/null @@ -1,3 +0,0 @@ -# Gitlab CI 集成文档 - ---- diff --git a/docs/guide/integrate-with-gitlab-ci.md b/docs/guide/integrate-with-gitlab-ci.md new file mode 100644 index 0000000..9754a34 --- /dev/null +++ b/docs/guide/integrate-with-gitlab-ci.md @@ -0,0 +1,25 @@ +# Integrate With Gitlab CI + +--- + +> GitLab is a single application for the entire DevOps lifecycle. + +## Configuration + +Set `RELIABLE_SERVER_URL` on demand. + +```yaml +before_script: + - export MARMOT_SERVER_URL=http://reliable-host + - export PATH=$PWD/node_modules/.bin:$PATH + - echo $PATH +test: + image: macacajs/macaca-electron-docker + script: + - npm i reliable-cli + - reliable report + tags: + - swarm +``` + +[gitlab]: https://about.gitlab.com/install/ diff --git a/docs/archive/integrate-with-jenkins.md b/docs/guide/integrate-with-jenkins.md similarity index 96% rename from docs/archive/integrate-with-jenkins.md rename to docs/guide/integrate-with-jenkins.md index 8e65ddc..0650b3c 100644 --- a/docs/archive/integrate-with-jenkins.md +++ b/docs/guide/integrate-with-jenkins.md @@ -1,4 +1,4 @@ -Integrate With Jenkins +# Integrate With Jenkins --- @@ -52,4 +52,4 @@ Change `$HOME/reliable_home/jenkins_home/config.xml` useSecurity to false, and r - [jenkins-android.md](./jenkins-android.md) - [jenkins-ios.md](./jenkins-ios.md) -- [jenkins-web.md](./jenkins-web.md) \ No newline at end of file +- [jenkins-web.md](./jenkins-web.md) diff --git a/docs/archive/jenkins-android.md b/docs/guide/jenkins-android.md similarity index 100% rename from docs/archive/jenkins-android.md rename to docs/guide/jenkins-android.md diff --git a/docs/archive/jenkins-ios.md b/docs/guide/jenkins-ios.md similarity index 100% rename from docs/archive/jenkins-ios.md rename to docs/guide/jenkins-ios.md diff --git a/docs/archive/jenkins-web.md b/docs/guide/jenkins-web.md similarity index 100% rename from docs/archive/jenkins-web.md rename to docs/guide/jenkins-web.md diff --git a/docs/guide/reliable-cli.md b/docs/guide/reliable-cli.md new file mode 100644 index 0000000..7319d52 --- /dev/null +++ b/docs/guide/reliable-cli.md @@ -0,0 +1,138 @@ +# Reliable-CLI + +--- + +## Installment + +```bash +$ npm i reliable-cli -g +``` + +## Usage + +### report + +```bash +$ reliable report -c ./reliable.config.js +``` + +## Configuration + +```javascript +module.exports = { + files: [ + `build/Release-iphonesimulator/${pkg.name}.app` + ], + packages: [ + { + version, + path: `${pkg.name}.app`, + } + ], + testInfo: { + }, + extraInfo: { + } +}; +``` + + +| key | value type | description | +| --- | --- | --- | +| files | `string[]` | extra build artifacts | +| packages | `Obejct[]` | core build artifacts | +| testInfo | `Object` | test coverage report | +| extraInfo | `Object` | extra infomation | +| environment | `Object` | ci runner environment | +| gitCommitInfo | `Object` | last commit log by [last-commit-log](//github.com/node-modules/last-commit-log/) | + + +```json +{ + "files": [], + "packages": [ + ], + "testInfo": { + "tests": 4, + "passes": 4, + "linePercent": 91.67, + "passPercent": 100, + "testHtmlReporterPath": "http://your-storage-host/example/c153d93/reports/index.html", + "coverageHtmlReporterPath": "http://your-storage-host/example/c153d93/coverage/index.html" + }, + "extraInfo": { + "webpack": "4.27.1", + "macaca-wd": "2.1.8", + }, + "environment": { + "ci": { + "JOB_NAME": "reliable", + "RUNNER_TYPE": "GITLAB_CI", + "BUILD_NUMBER": "123" + }, + "os": { + "platform": "linux", + "nodeVersion": "v8.12.0" + }, + "platform": "web" + }, + "gitCommitInfo": { + "body": "", + "hash": "9a5ebe6da33ba87a2a70947db2297c0bc3195de1", + "author": { + "date": "1545019270", + "name": "user", + "email": "user@macacajs.com", + "relativeDate": "2 minutes ago" + }, + "gitTag": "", + "gitUrl": "http://gitlab.com/app/reliable", + "subject": "feat: update reliable", + "committer": { + "date": "1545019270", + "name": "user", + "email": "user@macacajs.com", + "relativeDate": "2 minutes ago" + }, + "gitBranch": "feat/toast", + "gitRemote": "http://gitlab-ci-token/app/reliable.git", + "shortHash": "9a5ebe6", + "sanitizedSubject": "feat-update" + } +} +``` + +## Helper Methods + +User helper methods to resolve the iOS and Android platforms. + +```javascript +const helper = require('reliable-cli').helper; +const { + iosUtils, + androidUtils, + webUtils, +} = helper; + +// frequently methods + +https://macacajs.github.io/reliable-cli/ + +``` + +## Environment Variable + + | name | description | +| ----------------- | ---------------------------- | +| RELIABLE_SERVER_URL | server url for Reliable server | + +```bash +$ RELIABLE_SERVER_URL=http://127.0.0.1:9900 ci.sh +``` + +## Integration Samples + +- [ios-app-bootstrap](//github.com/app-bootstrap/ios-app-bootstrap) +- [android-app-bootstrap](//github.com/app-bootstrap/android-app-bootstrap) +- [awesome-practice-projects](//github.com/app-bootstrap/awesome-practice-projects) +- [web-app-bootstrap](//github.com/app-bootstrap/web-app-bootstrap) diff --git a/docs/archive/marmot-web-deploy.md b/docs/guide/reliable-web-deploy.md similarity index 91% rename from docs/archive/marmot-web-deploy.md rename to docs/guide/reliable-web-deploy.md index ce63e60..7a39709 100644 --- a/docs/archive/marmot-web-deploy.md +++ b/docs/guide/reliable-web-deploy.md @@ -54,6 +54,5 @@ should edit [docker-compose.yml](../docker-compose.yml) on demand. ### Using [docker](https://docs.docker.com/) -- [reliable-web](../docker/reliable-web/README.md) -- [reliable-mysql](../docker/reliable-mysql/README.md) -- [reliable-nginx](../docker/reliable-nginx/README.md) +- [reliable-web](../../docker/reliable-web/README.md) +- [reliable-mysql](../../docker/reliable-mysql/README.md) diff --git a/docs/zh/README.md b/docs/zh/README.md index 6ac14cc..2eb7bba 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -20,3 +20,9 @@ Reliable 适合在持续集成阶段与现有研发流程打通和衔接，当 ::: ![](https://wx3.sinaimg.cn/large/6d308bd9ly1fz3wii2wqsj21bh0u0qij.jpg) + +::: tip 部署便捷 +Reliable 一键部署，拥有自己的测试管理平台。 +::: + +![](http://ww2.sinaimg.cn/large/6d308bd9gw1f5scrp1p4rj20rs0gatbj.jpg) diff --git a/docs/zh/guide/integrate-with-gitlab-ci.md b/docs/zh/guide/integrate-with-gitlab-ci.md new file mode 100644 index 0000000..71656d8 --- /dev/null +++ b/docs/zh/guide/integrate-with-gitlab-ci.md @@ -0,0 +1,23 @@ +# Gitlab CI 集成 + +--- + +## GitLab-CI 配置 + +最简单的配置如下： + +其中 RELIABLE_SERVER_URL 按照具体上报的 Reliable 事例地址。 + +```yaml +before_script: + - export MARMOT_SERVER_URL=http://reliable-host + - export PATH=$PWD/node_modules/.bin:$PATH + - echo $PATH +test: + image: macacajs/macaca-electron-docker + script: + - npm i reliable-cli + - reliable report + tags: + - swarm +``` diff --git a/docs/archive/integrate-with-jenkins.zh-CN.md b/docs/zh/guide/integrate-with-jenkins.md similarity index 98% rename from docs/archive/integrate-with-jenkins.zh-CN.md rename to docs/zh/guide/integrate-with-jenkins.md index 2c1f272..6156e0a 100644 --- a/docs/archive/integrate-with-jenkins.zh-CN.md +++ b/docs/zh/guide/integrate-with-jenkins.md @@ -1,4 +1,4 @@ -# Jenkins 集成文档 +# Jenkins 集成 --- diff --git a/docs/archive/jenkins-android.zh-CN.md b/docs/zh/guide/jenkins-android.md similarity index 100% rename from docs/archive/jenkins-android.zh-CN.md rename to docs/zh/guide/jenkins-android.md diff --git a/docs/archive/jenkins-ios.zh-CN.md b/docs/zh/guide/jenkins-ios.md similarity index 100% rename from docs/archive/jenkins-ios.zh-CN.md rename to docs/zh/guide/jenkins-ios.md diff --git a/docs/archive/jenkins-web.zh-CN.md b/docs/zh/guide/jenkins-web.md similarity index 100% rename from docs/archive/jenkins-web.zh-CN.md rename to docs/zh/guide/jenkins-web.md diff --git a/docs/zh/guide/reliable-cli.md b/docs/zh/guide/reliable-cli.md new file mode 100644 index 0000000..8f158ac --- /dev/null +++ b/docs/zh/guide/reliable-cli.md @@ -0,0 +1,140 @@ +# 上报客户端 + +--- + +## 安装 + +```bash +$ npm i reliable-cli -D +``` + +## 使用 + +### 上报 + +```bash +$ reliable report -c ./reliable.config.js +``` + +## 脚本配置 + +```javascript +module.exports = { + files: [ + `build/Release-iphonesimulator/${pkg.name}.app` + ], + packages: [ + { + version, + path: `${pkg.name}.app`, + } + ], + testInfo: { + }, + extraInfo: { + } +}; +``` + +## 完整配置 + +| key | value type | description | +| --- | --- | --- | +| files | `string[]` | 构建附属产物 | +| packages | `Obejct[]` | 构建产物 | +| testInfo | `Object` | 测试覆盖率和通过率 | +| extraInfo | `Object` | 额外统计的数据，比如依赖版本信息等 | +| environment | `Object` | ci 运行环境信息 | +| gitCommitInfo | `Object` | git commit 信息 by [last-commit-log](//github.com/node-modules/last-commit-log/) | + +上报内容如下： + +```json +{ + "files": [], + "packages": [ + ], + "testInfo": { + "tests": 4, + "passes": 4, + "linePercent": 91.67, + "passPercent": 100, + "testHtmlReporterPath": "http://your-storage-host/example/c153d93/reports/index.html", + "coverageHtmlReporterPath": "http://your-storage-host/example/c153d93/coverage/index.html" + }, + "extraInfo": { + "webpack": "4.27.1", + "macaca-wd": "2.1.8", + }, + "environment": { + "ci": { + "JOB_NAME": "reliable", + "RUNNER_TYPE": "GITLAB_CI", + "BUILD_NUMBER": "123" + }, + "os": { + "platform": "linux", + "nodeVersion": "v8.12.0" + }, + "platform": "web" + }, + "gitCommitInfo": { + "body": "", + "hash": "9a5ebe6da33ba87a2a70947db2297c0bc3195de1", + "author": { + "date": "1545019270", + "name": "user", + "email": "user@macacajs.com", + "relativeDate": "2 minutes ago" + }, + "gitTag": "", + "gitUrl": "http://gitlab.com/app/reliable", + "subject": "feat: update", + "committer": { + "date": "1545019270", + "name": "user", + "email": "user@macacajs.com", + "relativeDate": "2 minutes ago" + }, + "gitBranch": "feat/toast", + "gitRemote": "http://gitlab-ci-token/app/reliable.git", + "shortHash": "9a5ebe6", + "sanitizedSubject": "feat-update" + } +} +``` + +## 工具函数 + +客户端预置了很多各平台常需要的工具函数。 + +```javascript +const helper = require('reliable-cli').helper; +const { + iosUtils, + androidUtils, + webUtils, +} = helper; + +// frequently methods + +https://macacajs.github.io/reliable-cli/ + +``` + +## 环境变量 + +| name | description | +| ----------------- | ---------------------------- | +| RELIABLE_SERVER_URL | Reliable 服务端的访问地址 | + +```bash +$ RELIABLE_SERVER_URL=http://127.0.0.1:9900 ci.sh +``` + +## 集成示例 + +- [ios-app-bootstrap](//github.com/app-bootstrap/ios-app-bootstrap) +- [android-app-bootstrap](//github.com/app-bootstrap/android-app-bootstrap) +- [awesome-practice-projects](//github.com/app-bootstrap/awesome-practice-projects) +- [web-app-bootstrap](//github.com/app-bootstrap/web-app-bootstrap) diff --git a/docs/archive/marmot-web-deploy.zh-CN.md b/docs/zh/guide/reliable-web-deploy.md similarity index 90% rename from docs/archive/marmot-web-deploy.zh-CN.md rename to docs/zh/guide/reliable-web-deploy.md index 1617367..b8e1298 100644 --- a/docs/archive/marmot-web-deploy.zh-CN.md +++ b/docs/zh/guide/reliable-web-deploy.md @@ -1,4 +1,4 @@ -# Reliable Web 部署文档 +# Web 服务部署 --- @@ -54,6 +54,5 @@ Nginx 服务默认运行在 `http://127.0.0.1:9920`。 ### 其他 [Docker](https://docs.docker.com/) 服务部署 -- [reliable-web](../docker/reliable-web/README.md) -- [reliable-mysql](../docker/reliable-mysql/README.md) -- [reliable-nginx](../docker/reliable-nginx/README.md) +- [reliable-web](../../docker/reliable-web/README.md) +- [reliable-mysql](../../docker/reliable-mysql/README.md)