贡献指引

致新贡献者

欢迎你的到来,非常感谢你愿意一起建设 DevStream 💖。

初次参与,你遇到任何问题都可以直接反馈与联系社区,包括但不限于:

  • 开发环境搭建时遇到任何问题。
  • 快速开始(quick start) 文档遇到任何问题。
  • 自动化脚本的任何问题。

如果你在运行项目的时候发现任何不符合预期或不合理的地方,请直接提交 Bug 报告!

如何贡献

我们欢迎各种贡献,包括但不限于:

  • 新功能(feature)
  • 代码构建、CI/CD
  • Bug 修复
  • 文档
  • Issue 分类、发起、回复、管理、维护等(Issue Triage)
  • 在 微信群、Slack、邮件列表解答问题
  • 网站页面设计
  • 在各种媒体、博客文章宣传 DevStream
  • 发版管理

不是只有提交 Pull Request 才能与 DevStream 擦出火花,你还可以参与我们的 社区会议,或者直接联系我们(slack微信群)一起聊聊怎么共建社区。

参与社区会议

DevStream 真诚地欢迎每一个人参与我们的会议,不需要被邀请,直接来就行!哪怕你暂时没有贡献的想法,只是来听听,我们也非常热烈欢迎。来听,就够了。

  • 你可以在我们的 wiki 页面) 找到关于社区会议的详细信息
  • 也请加入我们的 Slack 频道 ,因为会议日程和重要的事情会在 Slack 公布。
  • 对于中国用户,也可以加 微信群
  • 第一次参会你可以不打开摄像头,简单地介绍自己就足够了。当然,如果你想多聊几句,无论是 Q&A 还是聊天,我们都非常欢迎。
  • 随着时间的推移与你对 DevStream 沟通的加深,我们希望你能自如地发表意见、对他人的想法提出反馈,甚至分享你的想法与经验。

寻找 Issue

你可以在 Issue 列表找到这样两个标签: good first issue 表示仅向新贡献者开放,help wanted 适合于所有贡献者。

  • good first issue 含有更多的描述信息与指导,往往只涉及一小部分,完成它不需要你熟悉整个项目。如果你是第一次参与 DevStream(甚至是第一次参与开源),非常推荐你从 good first issue 开始共建之旅。更多信息,请参阅 good first issue 文档
  • help wanted 指引了你在完成了 good first issue 后,适合继续贡献的地方。带有这个标签的 issue,除了核心贡献者外的任何人都可参与。更多信息,请参阅 help wanted 文档
  • 你不需要拘泥于带有这两个标签的 issue,其他任何你感兴趣的 issue,都可以直接参与,无论是方案修改建议、讨论与回复、还是代码。
  • 有时 good first issue 或 help wanted 因为社区过于热情导致暂时没有空余,只要你愿意,你仍可以参与贡献!直接在 Slack微信群 联系我们,告诉我们你愿意参与!

如果你对某个 issue 有兴趣,想完成对应内容,请在 issue 内留下评论,例如:”I want to work on this”。

寻求帮助

在贡献时,向我们提问的最好的方式如下:

我们更推荐你在 GitHub 或 Slack 提问,这有助于技术讨论被沉淀下来,以帮助后来的贡献者。

Pull Request 流程与指南

针对 PR、贡献者和审阅者的不成文规则(我们不想有那么多条条框框,但这确实能为你减少不必要的时间浪费)。

  • 我们鼓励贡献者提交 PR,即使它处于“work-in-progress”状态。
  • 如果你的 PR 代码还没完成编写,请使用 GitHub 的 “draft PR“ 功能来告诉社区这个 PR 还在编写中。同时,这也意味着,你不一定要在所有代码完成后再 push,可以先实现大部分内容,提交个 draft PR,这有助于与社区及时交流沟通。
  • 当你的 PR 做好了被审阅(review)(处于非 draft PR 状态)的准备后,审阅者应在 24 小时内进行初始审阅。如果是周末或节假日,可能会延迟。
  • PR 的作者应当主动请求审阅(request-review),或者在 PR 内评论与 @审阅者,也可直接通过社交媒体进行沟通。如果审阅者未在24小时内回复,请相信我们绝不是有意遗漏你,请再次提醒我们。
  • 微小的修改(甚至是拼写错误)也完全可以提 PR。不存在所谓的”小 PR”,不必担心 PR 过小导致代码不被合并。
  • 无论是较大的 PR 还是较小的,我们建议你创建一个对应的 issue 以持续跟进与追踪。
  • 我们没有特定的特性分支。通常,你会将 PR 并入主分支。如果它针对于特定某个版本的错误修复,请确保你的 PR 请求合并的是该特定分支。
  • 如果你想贡献,但不想通过提 PR 来贡献,可以在 Slack 频道、微信群。或直接在 Issue、PR 下告诉我们,以便 maintainer 直接提交 PR。
  • 如果你长期未回复 maintainer(通常是一个月),你的 PR 可能会被关闭,敬请谅解。
  • 目前,我们不会定期发布,因此无法保证你的 PR 何时包含在下一个版本中。但是,我们正在尽最大努力使发布尽可能频繁。
  • 为了鼓励贡献者,你可以在未100%完成原有设计的情况下,完成相应的任务,即关闭 issue 与合并 PR。在这种情况下,你可以再创建个新的 issue,并提交个新的 PR 来完成之前遗漏的工作。我们不希望你在一个 PR 上耗时太久,这会打击你的兴趣。

更多关于 GitHub 协作的文档,可参考 GitHub 协作流程指引

开发

架构解读

文档类贡献

代码提交署名(Sign Off)

授权与认证(licensing) 对于开源项目非常重要,它确保了软件能基于作者提供的条款继续运作。我们需要你在贡献代码的时候署名你的提交,Developer Certificate of Origin (DCO) 是一种认证你编写了此段代码,并表明你持有这段代码的方式。

你可以通过在提交信息(Git Commit Message)中附加这段信息。注意,你的署名必须与 Git 的用户名和邮箱对应。

Text Only

  1. This is my commit message
  2. Signed-off-by: Your Name <your.name@example.com>

Git 有一个 -s 的命令行选项可以帮助你自动署名:

Text Only

  1. git commit -s -m 'This is my commit message'

如果你忘记了署名操作,但未将代码提交到远程仓库,可以通过这行命令来补充署名信息:

Text Only

  1. git commit --amend -s

Pull Request 检查项清单

当你提交 PR 或向其推送新提交时,我们的自动化系统将对你的新代码运行一些检查。我们要求你的 PR 通过这些检查,但在我们接受和合并它之前,我们还有更多的标准。我们建议你在提交代码之前在本地检查以下事项:

  • 检查代码格式问题(golangci-lint): 虽然我们的 CI 会在提交代码时自动运行 lint,但在本地先执行 lint 确保无误后再提交能节省你更多的精力与时间。
  • 构建/测试 代码,同上。
  • 仔细检查你的提交信息(Commit Message):详见 提交信息规范

Maintainer 团队

DevStream 由最初由 思码逸 Merico 的工程师们发起,并由 @IronCore864 带领。

目前,maintainer 们为:

  • @IronCore864
  • @daniel-hutao

注意:虽然 DevStream 由 Merico 发起,以及现在的 maintainer 们都来自 Merico,但我们不希望开源社区中存在 任何 专制的行为。我们将促进长期参与 member 和 reviewer 们加入 maintainer 队伍。我们欢迎来自任何公司与组织的你成为我们社区的一员。

你可以阅读 贡献者成长阶梯计划 以了解详情。