Skip to content

Latest commit

 

History

History
191 lines (131 loc) · 14.6 KB

CONTRIBUTING-template-zh.md

File metadata and controls

191 lines (131 loc) · 14.6 KB
Raw

介绍

在此写一些友好的内容！

首先，非常感谢你正在考虑为 Active Admin 进行贡献，没错，正是像你这样的人打造了 Active Admin 这么精良的工具。

[来源: Active Admin] **需要更多启发?**请参考： [1] Read The Docs [2] Mustache.js

告诉人们为什么应该读向导

了解向导的内容，有助于你和开发者的沟通，可以有效节省该开源项目的开发者管理和开发的宝贵时间。作为回报，他们会在回复你的issue、评估变更、以及完成你的 Pull Request 给予同样的尊重。

[来源: Hoodie]

解释你期望的贡献类型

保持开放的头脑！改进文档、bug 筛选、以及为任何有用处的贡献撰写教程，都会大大的减轻维护者的工作量。

ElasticSearch 是一款开源项目，而且我们非常热心的希望收到来自共同体的——你——的贡献！有很多种路径实现贡献：撰写教程、撰写博客、改进现有文档、提交bug报告、提交新功能需求、以及提交代码，均是为 Elasticsearch 自身内部合作的一部分。

[来源: Elasticsearch] 想获得更多启发?请参考： [1] Devise [2] Geocoder (“已知问题”)

解释你不想看到的贡献类型（如果有的话）

再重复一遍，做这些工作可以大大的减轻维护者的工作量。如果有人忽略掉你的向导指南，并提交了一些你最不想看到的内容，那么这个时候你就可以正当的关闭它，并告诉ta你的规程。

请不要使用 issue 跟踪来获得问题支持。请到 Freenode 上的 IRC 频道找 #pocoo 来进一步获得支持。如果你的问题不是直接和 Werkzeug 或 Flask 相关，#python 频道是非常活跃的有可能帮到你的，另外 Stack Overflow 也非常值得考虑。

[来源: Flask] 想获得更多启发?请参考： [1] cucumber-ruby [2] Read the Docs

基本规则

设定期望的行为（你的和他们的）

此处的信息不仅包括如何和他人沟通（彼此尊重、考虑对方等），也要包括技术上的责任（测试的重要性、项目依赖等），如果有行为准则的话，提示并将链接地址释出。

责任：

  • 确保每次变更跨平台的兼容性都能被接受：Windows、Mac、Debian& Ubuntu Linux。
  • 确保进入核心的代码满足检查表中的所有要求: https://gist.github.com/audreyr/4feef90445b9680475f2
  • 任何主要的变更和改进都要创建issue，以透明的方式进行讨论，且要获得共同体的反馈。
  • 除非是绝对必要的情况下，否则不要为代码增加新的类，Err on the side of using functions.
  • 尽可能的保持特性版本最小化，理想的情况是一个版本只有一个特性。
  • 对新来这表示友好！鼓励多样性，任何背景的贡献者都是欢迎的。请参考Python 共同体行为准则。

[来源: cookiecutter] 想获得更多启发?请参考： [1] Celery [2] geocoder

第一个贡献

帮助刚刚接触到贵项目的新人，最佳之处就是了解他们哪里需要帮助。而这通常也是一个展示你项目是否适合新手的好时机。

不确定如何开始为 Atom 做贡献？你可以先从那些标记为 beginner 或 help-wanted的issue入手： Beginner issues - 那些只需要几行代码就可以搞定，或者是做一到两个测试的 issues 。 Help wanted issues - 比 Beginner 更深度参与的 issues 。 上述 issue 列表，你可以将之按评论总数排序。虽然这么做有所缺陷，但是评论的数量可以合理地反映一个给定的变化将会产生的影响。

[来源: Atom] 想获得更多启发?请参考： [1] Read the Docs [2] Django (记得到下拉滚动到”向导“部分。)

可选项： 为从来都没有为开源贡献过的人添加资源链接

这里有一些友好的教程或许有所帮助：

正在为你的第一个 Pull Request 做准备吗？你可以从这个系列文章中学习到：在 GitHub 如何为开源项目做贡献

[来源: React]

附注一点，这里有一些来自Active Admin的例子，非常好的说明了对新人友好的语言来完善文档：

到达此处，说明你已经做出了改变！请大胆去寻求帮助吧，每个人在开始的时候都是新手:smile_cat:

如果说维护者要求你”rebase“你的PR，他们提及有很多代码做出了变更，那么你就应该照做，这样会节省合并的时间。

入门指南

给出如何提交贡献的快速路径

这部分的内容如何写取决于你自己，不过下面的内容最好是包含进来：

  • 告诉众人他们需要签署 CLA，同意 DCO，以及其它法律上的事情
  • 如果贡献需要测试，也让他们知道，并解释如何跑测试
  • 如果你使用了GitHub之外的issue管理工具（如JIRA、Trac），也请告诉他们如何去提交贡献

针对修改一两行内容之上的改动，应做到：

  1. 将代码fork到自己的账户
  2. 在自己的代码中进行修改
  3. 如果你认为修改很完善，且项目应该接受的话，要做到：
  • 确保代码风格是和项目一致的。
  • 和 jQuery 基金会签署了贡献者许可协议（CLA）
  • 知晓 jQuery 基金会的行为准则
  • 发送的 Pull Request 里包含 CLA 文件

[来源: Requirejs] 想获得更多启发?请参考： [1] Active Admin [2] Node.js [3] Ember.js

如果您对小的或“明显的”修复有不同的流程，请让他们知道

小的贡献(比如修正拼写错误)，其内容小到不属于知识产权，可以由贡献者作为补丁提交，而不需要签署 CLA。

根据经验，如果更改没有引入任何新功能或创造性思维，那么更改就是明显的修复。只要更改不影响功能，一些可能的示例包括:

  • 拼写、语法错误修正
  • 单词更正、空格和格式的变更
  • 注释清理
  • 变更返回值或者静态存储了错误的代码的Bug修复
  • 增加日志信息或 debug 的输出
  • 改动‘元数据’文件，如 Gemfile、.gitignore、构建脚本等。
  • 从一个目录或包移动文件到另外的目录或包

[来源: Chef] 想获得更多启发?请参考： [1] Puppet

如何报告缺陷

说明披露安全问题是的首要法则

至少，包括以下句子:

如果你发现了安全漏洞，请不要新建 issue，请发送 Email 给 xxx。

如果你不想使用自己的个人联系信息，那么需要开通“security@”的邮箱地址。更大一点的项目需要更多正式的流程来处理安全披露，如加密通信等。

任何事关安全的 issue 请直接提交到 [email protected]

为了确定自己是否在处理安全问题，请问自己以下两个问题:

  • 我可以访问不是我自己的内容吗？或者说我应该访问吗？
  • 我可以将其他人禁止使用吗？

如果以上两个问题的任何一个问题的答案是”是“的话，那么就可以认为这是一个安全问题。

提示：即使以上两个问题回答均为”否“，也不代表你处理的不是安全问题，实在确定不了的话，还请直接发送问题给[email protected]。

[来源: Travis CI] 需要更多启发?请参考 [1] Celery [2] Express.js

告诉你的贡献者如何撰写bug 报告

你可以准备好一些模板，这样人们就可以复制-粘贴（呵呵，再次节省你的工作）。

当提交一个issue，请确保回答了以下这五个问题：

  1. 你使用的是Go的哪个版本（go verison)?
  2. 使用的是什么处理器架构以及操作系统？
  3. 你做了什么？
  4. 你原本期望是什么？
  5. 实际运行的结果？

一般的问题请到 golang-nuts 邮件列表中，而不是在此issue跟踪，在那里 gopher 们会很好的回答你的问题。

[来源: Go] 想获得更多启发?请参考： [1] Celery [2] Atom (包括模板)

如何为新的功能和改进提建议

如果有特定的 roadmap、目标、原则、开发方式等，分享到这里

这些信息可以帮助到贡献者了解上下文，进而避免他们提出不符合项目需求的建议。（节省彼此的时间）

Express 的哲学思想是为 HTTP 服务提供小巧的、稳定的工具集，为单个页面应用、web站点、混合、或者是公开的 HTTP API提供伟大的解决方案。

Express 不会强制你使用任何特定的ORM 或模板引擎，通过Consolidate.js ，Express 提供了超过14中模板引擎，你可以快速的构建自己的完美框架。

[来源: Express] 想获得更多启发?请参考： Active Admin

解释建议某个特性所需的过程

如果是前后来回需要确认的话，那么这个解释就很必要了。询问他们功能的范围，仔细思考为什么这个功能是必须的，以及其将如何工作。

如果你发现了Elasticsearch没有你意想中的功能，你并不是第一位，也不是最后一位，请相信自己，一定会有其他有类似需求的人。Elasticsearch 有很多功能都是因为用户的需要而增加的，请在GitHub上新建一个issue，描述清楚你需要的功能，以及为何需要它，最好也描述一下它应该如何工作。

[source: Elasticsearch] 想获得更多启发?请参考： [1] Hoodie [2] Ember.js

代码核对（review）流程

解释代码提交之后如何能够被接受的全过程

谁来核对？在被接受之前需要谁的签名？贡献者希望在什么时候收到你的消息?贡献者如何获得提交访问(如果有的话)?

我们的核心团队会在每周的分类会议上查看 Pull Requests，会议是使用公开的Google Hangout进行。每周状态更新会发送到 puppet-dev 邮件列表。所有的注意事项都会记录到 Puppet 共同体 community-triage仓库，Hangout 同时也会上传到YouTube上。

在收到反馈后，我们期望在两周内得到答复。两周后，如果没有显示任何活动，我们可能会关闭pull request。

[来源: Puppet] 想获得更多启发?请参考 [1] Meteor [2] Express.js

共同体

如果你的项目除了 GitHub 之外还有其它的通道的话，一并在这里列出。还可以作者、维护者、亦或是贡献者都可以写上，或者是说明一下响应时间的期望。

你可以来 https://gitter.im/cucumber/cucumber 和我们的核心团队接触，我们会在周五提供专门的时间。

[来源: cucumber-ruby] 想获得更多启发?请参考： [1] Chef [2] Cookiecutter

可选项：代码、commit 约定、以及标签约定

以下这些内容并非必须项，但是对于简化贡献的流程等内容会有所帮助的。

解释项目有特别的代码风格，如果有的话。

可参考项目： [1] Requirejs [2] Elasticsearch

如果项目采用了一定的 commit 约定的话，请解释一番

可参考项目? [1] Angular [2] Node.js

如果项目的 issue 采用了标签约定的话，请解释一番

可参考项目? [1] StandardIssueLabels [2] Atom