From 5898aac64a01b695606d945303e0ecc7ef01422c Mon Sep 17 00:00:00 2001 From: clark-t Date: Mon, 23 Sep 2019 07:44:58 -0500 Subject: [PATCH] =?UTF-8?q?[=E6=96=87=E6=A1=A3=E4=BF=AE=E6=94=B9]=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=E5=9B=BD=E5=BA=86=E7=BB=B4=E6=8A=A4MIP=E7=AB=99?= =?UTF-8?q?=E9=95=BF=E5=B9=B3=E5=8F=B0=E7=9A=84=E6=96=87=E6=A1=A3=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=20(#700)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 新增国庆通知文档 * 增加部分规范说明 --- .../getting-start/component-spec.md | 3 +- .../getting-start/how-to-contribute.md | 53 +++++++++++++++++-- docs/contribute/getting-start/meta.json | 3 ++ docs/news/2019-09-23-19.md | 20 +++++++ docs/news/meta.json | 10 ++++ 5 files changed, 84 insertions(+), 5 deletions(-) create mode 100644 docs/news/2019-09-23-19.md diff --git a/docs/contribute/getting-start/component-spec.md b/docs/contribute/getting-start/component-spec.md index f7181295..49ca6be8 100644 --- a/docs/contribute/getting-start/component-spec.md +++ b/docs/contribute/getting-start/component-spec.md @@ -25,7 +25,6 @@ MIP 扩展组件开发采用 [Forking工作流](https://github.com/oldratlee/tra - JavaScript 规范 - CSS 规范 -
## 目录规范 @@ -122,7 +121,7 @@ MIP 自定义组件的配置项需符合 Camel 规范，不得采用中划线
## JavaScript 规范 -- [MUST] 组件的脚本开发必须遵守 JavaScript Standard Style [[CN](https://standardjs.com/rules-zhcn.html)/[EN](https://standardjs.com/rules-en.html)] 代码规范 +- [MUST] 组件的脚本开发必须遵守 JavaScript Standard Style （[CN](https://standardjs.com/rules-zhcn.html)/[EN](https://standardjs.com/rules-en.html)）代码规范 - [MUST] 组件的模版开发应该遵循 [Vue Style Guide](https://cn.vuejs.org/v2/style-guide/index.html) - [MUST] 禁止使用白名单之外的原生 JS API (参考：[沙盒机制](../principle/sandbox.md)) - [SHOULD] 使用 ES6 和 ES Module 模块化组织代码 diff --git a/docs/contribute/getting-start/how-to-contribute.md b/docs/contribute/getting-start/how-to-contribute.md index d8d4f78a..ab46d344 100644 --- a/docs/contribute/getting-start/how-to-contribute.md +++ b/docs/contribute/getting-start/how-to-contribute.md @@ -1,8 +1,10 @@ # 如何提交站长组件代码 -[notice]站长组件是扩展 MIP 功能的一种形式，在开发提交站长组件之前，请首先阅读[《请优先使用 MIP 现有机制和官方组件来实现业务功能》](./use-official-mip-first.md)一文，看看所需要开发的站长组件是否已被 MIP 现有的机制和官方组件覆盖了，从而减少开发和审核的时间成本。 +[notice]站长组件是扩展 MIP 功能的一种形式，在开发提交站长组件之前，请首先阅读[《请优先使用 MIP 现有机制和官方组件来实现业务功能》](./use-official-mip-first.md)一文，看看所需要开发的站长组件是否已被 MIP 现有的机制和官方组件覆盖了，覆盖到的功能将不会受理相关组件的提交审核。 -当前 MIP 的组件有内置组件、官方组件、站长组件几部分。其中，内置组件不支持开发者提交修改，官方组件是官方提供的较为通用的组件，开发者也可以通过 Pull Request 的方式[修改提交官方组件](./how-to-contribute-mip-extensions.md)。站长组件则是为了满足站点特殊定制化需求而提供的。下面介绍如何提交站长组件。 +当前 MIP 的组件有内置组件、官方组件、站长组件几部分。其中，内置组件包括 mip-img、mip-carousel 等等；官方组件是官方提供的功能较为通用的组件，开发者可以通过 Pull Request 的方式[修改提交官方组件](./how-to-contribute-mip-extensions.md)。站长组件则是为了满足站点特殊定制化需求，并且现有 MIP 通用机制无法涵盖而提供的一种功能拓展的形式。 + +下面介绍如何提交站长组件，以及说明提交审核的一些注意事项。 ## 提交站长组件 @@ -76,10 +78,12 @@ $ cd test.a.com 3.**发起 Pull Request** -开发完成后，[发起 pull Request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)。进入自己 fork 的仓库，点击 New pull request 按钮，按照提示，完成提交。最终会在官方仓库提交一个 Pull request。Pull request 提交后，会自动触发持续集成的任务，如代码规范检查、部署预览等，在 Conversation 选项卡可以看到实时状态。如果有不通过的，需要再次修改提交，确保所有检查项都成功通过，官方才能审核合入。 +开发完成后，[发起 Pull Request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)。进入自己 fork 的仓库，点击 New pull request 按钮，按照提示，完成提交。最终会在官方仓库提交一个 Pull request。Pull request 提交后，会自动触发持续集成的任务，如代码规范检查、部署预览等，在 Conversation 选项卡可以看到实时状态。如果有不通过的，需要再次修改提交，确保所有检查项都成功通过，官方才能审核合入。 ![github-status](./images/Picture5.png) +提交 Pull Request 需要遵守一定的规范要求，不符合要求的 PR 将会被打回或者是要求修改，具体请参考[PR 提交规范与审核标准](#PR提交规范与审核标注)。 + 4.**官方审核通过，合入上线** 官方审核通过后，代码将合入 `master` 分支并上线。若不通过，请根据反馈修改后再次提交。 @@ -90,3 +94,46 @@ $ cd test.a.com // 页面中引用 ``` + +## PR 提交规范与审核标准 + +### 提交规范 + +在提 PR 的时候，需要注意以下事项： + +1. 每个 PR 的代码只能针对单个组件进行新增或修改，不建议一次性提交多个组件的改动，以避免其中的部分组件因审核没通过而导致整体被打回； +2. 每个 PR 必须写明开发理由，尤其是说明 MIP 现有机制和官方组件为何不能覆盖开发需求； +3. 同时 PR 必须写明本次代码提交的相关改动说明，比如修复了什么问题、新增了什么功能； +4. 提交代码需完全符合[MIP 组件开发规范](./component-spec.md)的全部要求才会进入下一步的代码功能与代码逻辑审核； + +下面是一个简单的 PR 说明示例： + +```md +# 新增 mip-example 组件 + +## 开发理由 + +目前项目存在如下需求： XXXXXX，这个功能无法通过 MIP 现有机制实现，因此需要开发 mip-example 来实现相关功能。 + +## 组件说明 + +新增 mip-example 组件，实现如下功能： + +1. xxxx +2. xxxx +3. xxxx +``` + +### 审核标准 + +MIP 官方将严格按照以下原则进行组件审核，不符合要求的 Pull Request 将会打回要求修改，或者直接关闭 PR： + +- 组件功能能够直接通过 MIP 现有机制和 MIP 官方组件实现的，此类组件没有意义，将会直接打回； +- 组件不满足[《MIP 组件开发规范》](./component-spec.md)的要求的，此类组件不规范，将会直接打回； +- Pull Request 和 组件 REAME.md 不清晰导致审核人员无法理解组件的功能、用法的，会直接打回或要求补全相关文档。README.md 文档翔实度请参考官方组件； +- 审核人员给出审核意见但不进行修复，也不进行回复说明的，预期 1 个月 PR 无更新则直接 close PR。 + +[info] 最常见的一类站长组件是，前端发 AJAX 请求接口数据之后，在前端进行数据处理和 HTML 模板拼接，这种类型的组件可以直接使用 MIP 提供的[数据驱动与模板渲染](../../docs/interactive-mip/data-driven-and-dom-render.md)机制直接实现，无需额外进行站长组件提交，这类站长组件基本都会被直接打回。 + +[info] 最常见的一类组件开发规范问题是，组件没有满足 `mip-[站点标识]-[组件功能]` 的命名方式，即漏掉 `-[组件标识]-` 这个部分，开发者可以在提交前注意下这个问题。 + diff --git a/docs/contribute/getting-start/meta.json b/docs/contribute/getting-start/meta.json index a43929c2..ec6ba266 100644 --- a/docs/contribute/getting-start/meta.json +++ b/docs/contribute/getting-start/meta.json @@ -23,5 +23,8 @@ "name": "使用 MIP-CLI 开发组件", "key": "mip-cli-usage" } + ], + "ignore": [ + "contribute-with-mip-platform" ] } diff --git a/docs/news/2019-09-23-19.md b/docs/news/2019-09-23-19.md new file mode 100644 index 00000000..575d536d --- /dev/null +++ b/docs/news/2019-09-23-19.md @@ -0,0 +1,20 @@ +# MIP 站长组件审核平台维护通知 + +同时由于历史原因，目前 MIP 站长组件审核平台对 MIP 2.0 站长组件的审核管理方式不太友好，并且存在一些问题，因此需要暂时关闭维护，具体恢复时间将另行通知。在此期间开发者可以通过 github 提 Pull Request 的方式进行站长组件提交审核，可参考文档[《如何提交站长组件代码》](https://www.mipengine.org/v2/contribute/getting-start/how-to-contribute.html)进行相关学习。 + +需要重申的是，目前 MIP 核心机制结合官方组件已经基本涵盖了一般业务的开发需求，因此在提交站长组件之前，请首先确认好是否需要进行额外的站长组件开发工作，如确定需要开发，则需要在 PR 当中写明理由。 + +## 时间安排 + +具体的时间节点如下： + +- 2019.10.01 - 2019.10.07：国庆放假，暂停 MIP 站长组件的审核，收假后恢复审核工作； +- 2019.10.01 起：暂时关闭 MIP 站长组件审核平台的代码提交入口，具体恢复时间将另行通知。 + +## 参考文档 + +- [如何通过 GitHub 提交站长组件代码](https://www.mipengine.org/v2/contribute/getting-start/how-to-contribute.html) +- [请优先使用 MIP 现有机制和官方组件来实现业务功能](https://www.mipengine.org/v2/contribute/getting-start/use-official-mip-first.html) +- [MIP 交互式设计](https://www.mipengine.org/v2/docs/interactive-mip/introduction.html) +- [MIP 官方组件列表](https://www.mipengine.org/v2/components/index.html) + diff --git a/docs/news/meta.json b/docs/news/meta.json index 529931d9..7da7cd9d 100644 --- a/docs/news/meta.json +++ b/docs/news/meta.json @@ -1,5 +1,15 @@ { "menu": [ + { + "key": "2019-09-23-19", + "start": "2019-09-23 19:00:00", + "banner": { + "type": "notice", + "contents": [ + "MIP站长组件审核平台维护通知。>> 详情" + ] + } + }, { "key": "2019-04-28-14", "start": "2019-04-28 14:00:00",