zshshr closed pull request #283: [doc]update documents URL: https://github.com/apache/incubator-weex-site/pull/283
This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/docs/guide/contribute/bug-report-guidelines.md b/docs/guide/contribute/bug-report-guidelines.md index 63bca2114..ba6a74f0d 100644 --- a/docs/guide/contribute/bug-report-guidelines.md +++ b/docs/guide/contribute/bug-report-guidelines.md @@ -58,9 +58,3 @@ The aim to provide the reproducible steps is to enable developers to reproduce t The test results, including *Expected Result* and *Actual Result*, will tell developers what's wrong. *Expected Result* describes what should happen, and *Actual Result* describes what actually happens. -## Reference - -This document is a modified version of [1]. - - [1] http://testthewebforward.org/docs/bugs.html - diff --git a/docs/guide/contribute/development-process.md b/docs/guide/contribute/development-process.md index f0e503990..133e3775c 100644 --- a/docs/guide/contribute/development-process.md +++ b/docs/guide/contribute/development-process.md @@ -23,7 +23,7 @@ If you would like to create a new issue on Github, be sure to search the existin 2. Clone the forked repository and create a new branch from `master` to push your commits to. -3. Develop your feature or bug fix in your new branch. Make sure your code meets the [style guidelines](/development-process.html#code-style-guidelines). +3. Develop your feature or bug fix in your new branch. Make sure your code meets the [style guidelines](./development-process.html#code-style-guidelines). 4. Add the below mentioned copyright notice to the top of any new file(s) you've added. @@ -50,7 +50,7 @@ If you would like to create a new issue on Github, be sure to search the existin 5. Documentation and tests should be added or referenced if they need to be added or updated as part of the change. Make sure to test your changes thoroughly. -6. Commit all the changes to your branch. [Commit Guidelines](/development-process.html#commit-guidelines) must be followed for better understanding. +6. Commit all the changes to your branch. [Commit Guidelines](./development-process.html#commit-guidelines) must be followed for better understanding. ## 3. Create a Pull Request diff --git a/docs/guide/contribute/how-to-contribute.md b/docs/guide/contribute/how-to-contribute.md index 45c834def..0ce614522 100644 --- a/docs/guide/contribute/how-to-contribute.md +++ b/docs/guide/contribute/how-to-contribute.md @@ -10,21 +10,21 @@ version: 2.1 Apache Weex is an open source project that is under active development and we're continuously working out to simplify contributing to Weex ecosystem. Developers can participate and contribute to the Apache Weex community by reporting bugs, contributing code, answering questions, joining in discussions and contributing to documentation. ## Bugs -You can use Weex directly through [Getting Started](./guide/index.html) tutorial. If you encounter any unexpected phenomena during your use, feel free to let us know by filing a bug report. +You can use Weex directly through [Getting Started](../introduction.html) tutorial. If you encounter any unexpected phenomena during your use, feel free to let us know by filing a bug report. ##### Find Known Issues -We are using JIRA for tracking all the issues and updating whenever when have an internal fix in progress. Before filing a new task, try to confirm if it is already listed or if there is a fix in progress. +We are using [Github Issues](https://github.com/apache/incubator-weex/issues) for tracking all the issues and updating whenever when have an internal fix in progress. Before filing a new task, try to confirm if it is already listed or if there is a fix in progress. ##### Report New Issues -Open a [JIRA Issue](https://issues.apache.org/jira/projects/WEEX) , click on the top red "Create" button (you may need to [create a JIRA account](https://issues.apache.org/jira/secure/Signup!default.jspa) if you haven't registered). [Bug Report Guidelines](/bug-report-guidelines.html) document provides some of the most useful information about writing a good bug report. The better your bug report is, the faster we can reproduce and fix it! +Open a [Github Issues](https://github.com/apache/incubator-weex/issues) , click on the right top green "New Issue" button (you may need to create a Github account if you haven't registered). [Bug Report Guidelines](./bug-report-guidelines.html) document provides some of the most useful information about writing a good bug report. The better your bug report is, the faster we can reproduce and fix it! ## Contribute Code Apache Weex is an open source project and both, core team members and external contributors, send pull requests which go through the same review process. If you have already decided to start writing code in Weex, Congratulations! You’re up and running. -You can contribute code by either fixing an existing bug or developing new features. In either case, we always encourage to create a JIRA ticket and ensure we are in agreement on your proposal. +You can contribute code by either fixing an existing bug or developing new features. In either case, we always encourage to create a Github ticket and ensure we are in agreement on your proposal. -To help you get started, we've created a document with more details about development process. Please read **[Getting Started with Development Process](/development-process.html)**. +To help you get started, we've created a document with more details about development process. Please read **[Getting Started with Development Process](./development-process.html)**. ## Ask or Answer Questions diff --git a/docs/guide/platform-difference.md b/docs/guide/platform-difference.md index 249418ea2..e4b972063 100644 --- a/docs/guide/platform-difference.md +++ b/docs/guide/platform-difference.md @@ -1 +1,63 @@ # Platform Difference with Web + +Weex is a cross-platform solution. The web platform is just one of its runing environments, and it can also run on Android and iOS clients. The differences between the native platform and the web platform have some differences in functionality and development experience. + +## No DOM in Weex + +DOM (Document Object Model) is a concept in the Web. It is a programming interface for HTML and XML. Weex is a runtime environment that based on native applications, and native components are rendered in Android and iOS environments, not DOM Elements. + +### DOM operation is not supported + +The Web API is not supported, there are no objects such as `Element`, `Event`, `File`. For a detailed list, please refer to [Web APIs on MDN] (https://developer.mozilla.org/en-US/docs /Web/API). Selected elements are not supported, such as `document.getElementById` , `document.querySelector`; Of course, DOM API-based libraries (such as jQuery) are not supported. + +### Limited event type + +Weex supports binding events on tags, just like in browsers, but events in Weex are captured and triggered by native components. The behavior is different from the browser. The properties in the event are also difference from web. + ++ Support for some event types of the web. For details, please refer to [《Common events》](../docs/events/common-events.html)。 + ++ It does not distinguish between the capture phase and the bubbling phase of an event, which is equivalent to a DOM level 0 event. + +## No BOM in Weex + +BOM (Browser Object Model) is an interface provided by the browser environment for javascript. Weex is not based on the browser runing on the native side and does not support the BOM interface provided by the browser. + +### No `window` 、`screen` object + +The `window` and `screen` objects in the browser are not provided in Weex and global variables are not supported. If you want to get the screen or environment information of your device, you can use the `WXEnvironment` variable. + ++ `WXEnvironment` + + `weexVersion`: WeexSDK Version. + + `appName`: The name of application. + + `appVersion`: The verison of application. + + `platform`: The value maybe one of `Web` 、`Android` 、`iOS`. + + `osName`: The name of OS. + + `osVersion`: The version of OS. + + `deviceWidth`: The width of device. + + `deviceHeight`: The height of device. + +### No `document` object + +In the browser, `document` indicates the currently active document model. This object is not available in Android and iOS environments, and DOM operations related to it are not supported. + +### No `history` 、`location` 、`navigator` object + ++ `history` The history of the current page is saved and a forward and backward action is provided. ++ `location` Recorded information about the current page URL. ++ `navigator` Recorded information in the current browser. + +These interfaces are related to the implementation of the browser itself, which can control the forward and backward of the page and obtain status information. Although there are concepts of "history" and "navigation" in Android and iOS, but it is used for jumps between multiple administrative views. In other words, click "forward" and "backward" in the browser will still be in the same tab. In the native application, "forward" and "back" will actually jump to other pages. + +Weex also provides the `navigator` module to manipulate page jumps. For details, please refer to [《navigation control》](../docs/modules/navigator.html). + +## Ability to call mobile device native API + +The mobile device native API can be called in Weex by using the registration and calling module. Some of these modules are built into Weex, such as clipboard , navigator , storage , and so on. + ++ [《clipboard》](../docs/modules/clipboard.html) ++ [《navigator control》](../docs/modules/navigator.html) ++ [《storage》](../docs/modules/storage.html) + +In order to maintain the versatility of the framework, Weex's built-in native modules are limited, but Weex provides the ability to extend native modules. For specific extension methods, please refer to [《iOS extend》](./extend/extend-ios.html) 和[《Android extend》](./extend/extend-android.html)。 + +> Some interfaces also exist in the browser environment, but you should pay attention to browser compatibility when using them; for example, the clipboard function, for security reasons, most browsers restrict their use. diff --git a/docs/zh/guide/contribute/bug-report-guidelines.md b/docs/zh/guide/contribute/bug-report-guidelines.md index e69de29bb..6aac3f5df 100644 --- a/docs/zh/guide/contribute/bug-report-guidelines.md +++ b/docs/zh/guide/contribute/bug-report-guidelines.md @@ -0,0 +1,59 @@ +--- +title: Bug 报告指南 +type: community +has_chapter_content: false +version: 2.1 + +--- + +# Bug 报告指南 + +该文档描述了如何编写一个好的 Weex bug 报告。好的 bug 报告帮助开发者决定一个 bug 的优先级和严重性，并且增加了 bug 被快速修复的可能性，你能提供的具体信息越多越好。 + +## Bug 报告原则 + +- 避免重复:在报 bug 前先搜索! +- 总是测试最新的可用版本。 +- 每个报告只报一个 bug。 +- 陈述有用的事实，而不是意见或抱怨。 + +## 如何编写一个好的 Bug 报告 + +一个好的 bug 报告应该包括以下信息: + +### 标题 + +标题的目标是使 bug 能够被搜索并且唯一可识别。 + +一个坏的例子:`List Crash` + +一个很好的例子:`List Crashes when deleting a header` + +### 环境 + +**Weex 版本**: 请告知你在 bug 发生时使用的 WeexSDK 、Weex Playground 或 weex-toolkit 的版本 + +**设备环境**: 请告知你 bug 所发生的机型、平台和 OS 版本，例如：iPhone 6,iOS 10.3。 + +### 概述/描述 + +bug 报告的概述或描述是向开发者详细解释 bug，包括： + +- 为什么这是一个 bug +- 可以重现 bug 的 [dotwe](http://dotwe.org/vue/) 链接 +- 在视觉上可感知的 bug， 可以提供截屏 +- 对于 crash bug， 可以提供详细的堆栈 + +### 复现步骤 + +复现步骤的目标是帮助开发者在他自己的系统上重现 bug ，例如： + +步骤1：使用 Weex playgroud 扫码打开上面提供的 dotwe 链接 + +步骤2：滚动到列表底部 + +步骤3：点击红色按钮删除头部组件 + +### 测试结果 + +测试结果，包括预期结果和实际结果，预期结果描述了应该发生的事情，实际结果描述了实际发生的事情，从而表明这是个 bug 。 \ No newline at end of file diff --git a/docs/zh/guide/contribute/development-process.md b/docs/zh/guide/contribute/development-process.md index c6416923a..decfd45a1 100644 --- a/docs/zh/guide/contribute/development-process.md +++ b/docs/zh/guide/contribute/development-process.md @@ -16,7 +16,7 @@ 2. Clone 你 fork 出来的仓库，创建一个新的分支用于提交变更 -3. 编写需要开发的特性或 bug 修复代码，确保你的更改符合[代码风格指南](http://weex.apache.org/development-process.html#code-style-guidelines)。 +3. 编写需要开发的特性或 bug 修复代码，确保你的更改符合[代码风格指南](./development-process.html#代码风格指南)。 4. 复制并粘贴下面的注释到你的新文件顶部: @@ -43,7 +43,7 @@ 5. 修改或添加该变更相关de的文档和测试。 -6. 提交符合 [commit 指南](http://weex.apache.org/development-process.html#commit-guidelines) 的 commit 到你的分支。 +6. 提交符合 [commit 指南](./development-process.html#commit-指南) 的 commit 到你的分支。 ## 3. 创建一个 Pull Request diff --git a/docs/zh/guide/contribute/how-to-contribute.md b/docs/zh/guide/contribute/how-to-contribute.md index e69de29bb..a88a3cbeb 100644 --- a/docs/zh/guide/contribute/how-to-contribute.md +++ b/docs/zh/guide/contribute/how-to-contribute.md @@ -0,0 +1,55 @@ +--- +title: 如何参与贡献 +type: community +has_chapter_content: false +version: 2.1 +--- + +# 如何参与贡献 + +Apache Weex 是一个活跃的开源项目，我们一直致力于简化贡献 Weex 生态的流程。开源社区的贡献方式包括但不限于可以报 bug，回答开源社区、邮件组中的问题, 参与讨论新 feature 的方案，纠正或者更改文档， 同时我们也很欢迎直接贡献代码来完善和丰富 Weex。 + +## 报 Bug + +直接通过[快速上手](../introduction.html)教程开始使用 Weex，如果在使用过程中遇到任何问题和不符合预期的现象，都可以通过写一个 bug 报告来反馈。 + +##### 查找已知问题 +目前我们使用 [Github Issues](https://github.com/apache/incubator-weex/issues) 来跟踪所有的 issue 和 feature，只要对已知问题有修复或者有新 feature 计划的时候，都会更新对应的 issue 或者 feature 状态。 在填写 issue 或者 feature 时候，可以翻阅下是否已经有对应的 issue 或者 feature 已经在跟踪中。 + +##### 报告新 issue + +打开 [Github Issues](https://github.com/apache/incubator-weex/issues) ，点击右上方绿色的 "New Issue" 按钮（如果还没有注册 Github 账号则需要先注册）， [Bug 报告指南](./bug-report-guidelines.html) 文档提供了一些关于 Bug 报告中最有用的信息的细节提示。你的 Bug 报告写得越好，我们就能越快地重现和修复它！ + +## 贡献代码 + Weex 是一个开源的 Apache 社区项目，不管是核心团队或者外部开源社区的贡献者提交的 pull request 都需要通过同样的社区 code review 流程。 贡献代码可以通过修复已知的 bug 或者 开发新 feature，建议在贡献代码之前创建 Github issue(如果是修复 Github 中已经记录的 issue，可以直接使用该Github issue 的 ID)，我们写了一份关于[研发流程的文档](./development-process.html)，在开始之前可以先阅读一下。 + +## 提问或者回答问题 + +对于使用上的问题，建议你在 [stackoverflow.com](http://stackoverflow.com/) 平台上提问， 记得用 **weex** 标签标记它们。 + +你也可以查看所有的 [Weex相关问题](http://stackoverflow.com/questions/tagged/weex)，如果可以的话，尽可能帮助回答一些问题，这些问题常常是新手需要了解的基本概念和常见问题， 这也将帮助你更好地熟悉和使用 Weex 。 + +## 参与邮件组讨论 + +在 Weex 社区，大多数讨论都发生在邮件列表上。 + +dev 邮件组 "[email protected]" 是 Weex 开发人员交流和讨论新功能、新发布、开发流程的地方。 + +贡献者和开发者都应该订阅这个邮件组，以便了解到 Weex 项目所发生的事情以及表达自己的观点。 [(订阅)](mailto:[email protected]?subject=%28send%20this%20email%20to%20subscribe%29) [(退订)](mailto:[email protected]?subject=%28send%20this%20email%20to%20unsubscribe%29) [(档案)](http://mail-archives.apache.org/mod_mbox/incubator-weex-dev/) + +## 帮助提升文档质量 + +质量好的文档对开发者是极大的帮助。如果有一个功能强大的 API 但不易于使用，它就会变得毫无用处。所以， 我们欢迎任何贡献以帮助 Weex 的文档变得精确和易于阅读。 + +想要对文档进行更改，可以在 [weex-site 仓库](https://github.com/apache/incubator-weex-site)编辑对应的 Markdown 文件并创建一个 [Pull Request](https://help.github.com/articles/using-pull-requests/). + +## 如何成为 Committer + +Apache committer 是社区的核心成员，他们可以访问项目的仓库，也可以自己修改代码、文档和网站，也可以接受其他开发者的贡献。 + +我们正在招募 committer，我们所寻找的是积极参与到社区贡献同时对 Weex 有持续兴趣的同学。如果你有兴趣成为一名 Weex committer，可以联系现有的 committer 或者直接联系 dev 邮件组，欢迎你的加入！ + + +## License + + 默认你对 Weex 的贡献是基于 Apache License 2.0。 \ No newline at end of file diff --git a/docs/zh/guide/platform-difference.md b/docs/zh/guide/platform-difference.md index 54c2b0bb3..8e81585a1 100644 --- a/docs/zh/guide/platform-difference.md +++ b/docs/zh/guide/platform-difference.md @@ -8,18 +8,18 @@ DOM（Document Object Model），即文档对象模型，是 HTML 和 XML 文档 ### 不支持 DOM 操作 -既然原生环境中不支持 Web API，没有 `Element` 、`Event` 、`File` 等对象，详细列表可以参考 [Web APIs on MDN](https://developer.mozilla.org/en-US/docs/Web/API)。不支持选中元素，如 `document.getElementById` 、 `document.querySelector` 等；当然也不支持基于 DOM API 的程序库（如 jQuery）。 +原生环境中不支持 Web API，没有 `Element` 、`Event` 、`File` 等对象，详细列表可以参考 [Web APIs on MDN](https://developer.mozilla.org/en-US/docs/Web/API)。不支持选中元素，如 `document.getElementById` 、 `document.querySelector` 等；当然也不支持基于 DOM API 的程序库（如 jQuery）。 ### 有限的事件类型 Weex 支持在标签上绑定事件，和在浏览器中的写法一样，但是 Weex 中的事件是由原生组件捕获并触发的，行为和浏览器中有所不同，事件中的属性也和 Web 中有差异。 -+ 并不支持 Web 中所有的事件类型，详情请参考[《通用事件》](./common-events.html)。 ++ 支持 Web 中的事件类型，详情请参考[《通用事件》](../docs/events/common-events.html)。 + 不区分事件的捕获阶段和冒泡阶段，相当于 DOM 0 级事件。 ## Weex 环境中没有 BOM -BOM（Browser Object Model），即浏览器对象模型，是浏览器环境为 javascript 提供的接口。Weex 在原生端没有并不基于浏览器运行，不支持浏览器提供的 BOM 接口。 +BOM（Browser Object Model），即浏览器对象模型，是浏览器环境为 javascript 提供的接口。Weex 在原生端并不基于浏览器运行，不支持浏览器提供的 BOM 接口。 ### 没有 `window` 、`screen` 对象 @@ -47,16 +47,16 @@ Weex 中并未提供浏览器中的 `window` 和 `screen` 对象，不支持使 这些接口与浏览器自身的实现有关，可以控制页面的前进后退并且获取状态信息。虽然在 Android 和 iOS 中也有“历史”和“导航”的概念，但是它是用于多个管理视图之间的跳转的。换句话说，在浏览器中执行“前进”、“后退”仍然会处于同一个页签中，在原生应用中“前进”、“后退”则会真实的跳转到其他页面。 -此外 Weex 也提供了 `navigator` 模块来操作页面的跳转，使用方法参考[《navigator 导航控制》](/cn/references/modules/navigator.html)。 +此外 Weex 也提供了 `navigator` 模块来操作页面的跳转，使用方法参考[《navigator 导航控制》](../docs/modules/navigator.html)。 ## 能够调用移动设备原生 API 在 Weex 中能够调用移动设备原生 API，使用方法是通过注册、调用模块来实现。其中有一些模块是 Weex 内置的，如 clipboard 、 navigator 、storage 等。 -+ [《clipboard 剪切板》](/cn/references/modules/clipboard.html) -+ [《navigator 导航控制》](/cn/references/modules/navigator.html) -+ [《storage 本地存储 》](/cn/references/modules/storage.html) ++ [《clipboard 剪切板》](../docs/modules/clipboard.html) ++ [《navigator 导航控制》](../docs/modules/navigator.html) ++ [《storage 本地存储 》](../docs/modules/storage.html) -为了保持框架的通用性，Weex 内置的原生模块有限，不过 Weex 提供了横向扩展的能力，可以扩展原生模块，具体的扩展方法请参考[《iOS 扩展》](/cn/index.html) 和[《Android 扩展》](/cn/guide/extend-android.html)。 +为了保持框架的通用性，Weex 内置的原生模块有限，不过 Weex 提供了横向扩展的能力，可以扩展原生模块，具体的扩展方法请参考[《iOS 扩展》](./extend/extend-ios.html) 和[《Android 扩展》](./extend/extend-android.html)。 > 有些接口在浏览器环境中也存在，不过在使用时应该注意浏览器的兼容性；如剪贴板功能，出于安全性考虑，绝大多数浏览器都限制其使用。 ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
