jianhan-he closed pull request #240: [doc] add contribute document URL: https://github.com/apache/incubator-weex-site/pull/240
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/zh/guide/contribute/development-process.md b/docs/zh/guide/contribute/development-process.md index e69de29bb..599fbfa01 100644 --- a/docs/zh/guide/contribute/development-process.md +++ b/docs/zh/guide/contribute/development-process.md @@ -0,0 +1,98 @@ +# 开发流程 + +本文档描述了如何对 Weex 源代码进行更改和提交，以下是建议的步骤： + +## 1. 选择或创建一个 JIRA issue单 + +目前 Weex 使用 [JIRA Issue](https://issues.apache.org/jira/projects/WEEX) 来跟踪所有类型的代码更改，而不仅仅是 bug 修复，我们使用 Github Pull Request 来管理代码 review 和合并特定的代码更改。也就是说，JIRA用于描述什么是需要修复或更改的，Pull Request 用于描述这些修复和变更如何实现。 + +在创建新问题之前一定要先搜索问题，避免重复。如果你的更改可能需要和其他开发者进行讨论，你可以在 [weex-dev](mailto:[email protected]) 邮件列表中创建一个讨论。 + +**每个 PR 都应该对应于 JIRA 中的一个 issue。** + +## 2. 编写代码 + +1. [Fork](https://help.github.com/articles/fork-a-repo/) 在 <https://github.com/apache/incubator-weex> 上的 Github 仓库 + +2. Clone 你 fork 出来的仓库，创建一个新的分支用于提交变更 + +3. 编写需要开发的特性或 bug 修复代码，确保你的更改符合[代码风格指南](http://weex.apache.org/development-process.html#code-style-guidelines)。 + +4. 复制并粘贴下面的注释到你的新文件顶部: + + ``` + /* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + ``` + +5. 修改或添加该变更相关de的文档和测试。 + +6. 提交符合 [commit 指南](http://weex.apache.org/development-process.html#commit-guidelines) 的 commit 到你的分支。 + +## 3. 创建一个 Pull Request + +[创建一个 pull request](https://help.github.com/articles/using-pull-requests/) 并提交到 `apache/incubator-weex` 的 `master` 分支，确保它符合这些准则: + +1. 一个 Pull Request 只解决一个问题 +2. PR标题应该是 `[WEEX-xxxx][模块]标题`，其中 `xxxx` 是相关的 JIRA 问题号，模块是 PR 的类别（android、iOS、jsfm、web、component、doc、website、test、other），标题可以是 JIRA 的标题，也可以是描述 PR 本身的更具体的标题。 +3. 如果该 PR 相关的工作还在进行中，还没有准备好被合并，但需要被推到 Github 上以方便查看，可以在模块后添加 `[WIP]` 标示。 + +## 代码风格指南 + +### Objective-C + +- 用 tab 缩进而不是空格 + +- `*` 操作符靠近变量名（如 Type *variable） +- 方法定义：大括号需要另起一行 +- 其他大括号：开括号紧跟在代码后面，不另起一行，闭括号单独占一行 +- 使用 `#pragma marks` 标记将方法分类 +- 遵循 [GitHub Objective-C Style Guide](https://github.com/github/objective-c-style-guide) 中其他的代码风格指南 + +### Java & Android + +- 使用 [Google Java Style](https://google.github.io/styleguide/javaguide.html) 作为基本的 Java 代码风格指南 +- 其他 android 相关代码需遵循 [AOSP Code Style](https://source.android.com/source/code-style.html) + +### C & C++ + +* 整体使用[Google C++ Style](https://google.github.io/styleguide/cppguide.html)作为C++代码风格指南 +* Weex定义了一套[Google C++ 开发规范子集](https://github.com/jianhan-he/C-Style-Guide/blob/master/C%2B%2B%20Style%20Guide.md)，涵盖了一些主要C++场景使用规范 + +## Commit 指南 + +使用下面的形式来写 commit 描述: + +``` +Summary of change, same as PR title: `[WEEX-xxxx][COMPONENT] Summary` + +Longer description of change addressing as appropriate: why the change +is made,context if it is part of many changes, description of previous +behavior andnewly introduced differences, etc. + +Long lines should be wrapped to 80 columns for easier log message +viewing interminals. + +Bug: 123456 +``` + +一个简短的主题紧跟一个空行再接着写 commit 的详细描述，Bug 这里使用的是来自 JIRA 的问题号。 + +在[这里](https://chris.beams.io/posts/git-commit/)可以找到一些关于如何编写 commit message 的好方法。 + diff --git a/docs/zh/guide/contribute/how-to-contribute.md b/docs/zh/guide/contribute/how-to-contribute.md index e69de29bb..3738eb5b0 100644 --- a/docs/zh/guide/contribute/how-to-contribute.md +++ b/docs/zh/guide/contribute/how-to-contribute.md @@ -0,0 +1,49 @@ +# 如何参与贡献 + +Apache Weex 是一个活跃的开源项目，我们一直致力于简化贡献 Weex 生态的流程。开源社区的贡献方式包括但不限于可以报 bug，回答开源社区、邮件组中的问题, 参与讨论新 feature 的方案，纠正或者更改文档， 同时我们也很欢迎直接贡献代码来完善和丰富 Weex。 + +## 报 Bug + +直接通过[快速上手](http://weex.apache.org/guide/index.html)教程开始使用 Weex，如果在使用过程中遇到任何问题和不符合预期的现象，都可以通过写一个 bug 报告来反馈。 + +##### 查找已知问题 + +目前我们使用 [JIRA](https://issues.apache.org/jira/projects/WEEX) 来跟踪所有的 issue 和 feature，只要对已知问题有修复或者有新 feature 计划的时候，都会更新对应的 issue 或者 feature 状态。 在填写 issue 或者 feature 时候，可以翻阅下是否已经有对应的 issue 或者 feature 已经在跟踪中。 + +##### 报告新 issue + +打开 [JIRA Issue](https://issues.apache.org/jira/projects/WEEX) ，点击最上方红色的 “Create” 按钮（如果还没有注册 JIRA 账号则需要[先注册一下](https://issues.apache.org/jira/secure/Signup!default.jspa)）， [Bug 报告指南](http://weex.apache.org/bug-report-guidelines.html) 文档提供了一些关于 Bug 报告中最有用的信息的细节提示。你的 Bug 报告写得越好，我们就能越快地重现和修复它！ + +## 贡献代码 + +Weex 是一个开源的 Apache 社区项目，不管是核心团队或者外部开源社区的贡献者提交的 pull request 都需要通过同样的社区 code review 流程。 贡献代码可以通过修复已知的 bug 或者 开发新 feature，建议在贡献代码之前创建 JIRA issue(如果是修复 JIRA 中已经记录的 issue，可以直接使用该JIRA issue 的 ID)，我们写了一份关于[研发流程的文档](http://weex.apache.org/development-process.html)，在开始之前可以先阅读一下。 + +## 提问或者回答问题 + +对于使用上的问题，建议你在 [stackoverflow.com](http://stackoverflow.com/) 平台上提问， 记得用 **weex** 标签标记它们。 + +你也可以查看所有的 [Weex相关问题](http://stackoverflow.com/questions/tagged/weex)，如果可以的话，尽可能帮助回答一些问题，这些问题常常是新手需要了解的基本概念和常见问题， 这也将帮助你更好地熟悉和使用 Weex 。 + +## 参与邮件组讨论 + +在 Weex 社区，大多数讨论都发生在邮件列表上。 + +dev 邮件组 “[[email protected]](mailto:[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 ---------------------------------------------------------------- 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
