Does you organization want to host InnerSource Summit 2025? Click here to apply or contact us at info@innersourcecommons.org to find out more

贡献机制

你准备好开始为其他团队项目/仓库做出贡献了吗?你是否希望通过协作而不是通过管理升级来减少阻碍?本节给出了实用的建议,并重点介绍了在 为InnerSource 做出贡献时要记住的问题。它使你和项目团队有尽可能的愉快的体验,为更多的贡献和伟大的合作奠定基础。

本文分为你可能会经历的三个步骤

当你的贡献和目标越来越多,你可能会重复地经历其中一些步骤。很有可能当你这样做的时候,一切都会变得越来越自然——也许你甚至会奇怪你什么时候做过那些步骤。

准备工作

交付周期

一个关键的区别是项周转时间。每当你有第一次贡献的时候,你都会加入一个新的(维护)团队。因此,你需要了解他们的代码、所使用的技术以及他们喜欢的开发环境(比如测试框架、构建系统)。即使在这种类型的工具已标准化的情况下,每个团队也会开发出一些单独的特性。除了技术方面,你可能面临沟通上的分歧(比如代码评审)。即使当你过一段时间再回来,团队的工作方式和成员可能已经改变了。你得花点时间去了解一个你很久没见的朋友,因为你现在正要去拜访他。

给自己足够的准备时间。尽早开始,这样你的努力就可以在你需要的时候发挥作用。最好在先享受你的空闲时光——当你和维护团队一起工作时,你会对项目周转时间有更明显的感觉。通常,你会注意到,在为维护团队做出一些成功的贡献之后,维护团队的项目周转时间都会减少。在开源项目中也是一样,你可以在 这里 阅读更多关于它的内容。

期望管理

在你以往的团队中,每个人都对预期的交付周期有一个概念。在InnerSource中可能不是这样的,这可能是由于时差较大(例如美国西雅图的PDT与德国柏林的CEST)或你将不能像以往的团队一样全职工作,即使你们在一个地区。因此,为了防止双方都感到沮丧、不耐烦和其他不信任的影响,你需要明确地对自己的预期的反应时间进行期望管理。一种方法是快速的回复 Trusted Committer :“我得过几天后才能看看”,如果你知道你得几天后才有空。理想情况下,当你有空时可以给他们一个粗略的时间预估。这样做即使在非物理接触,在更长的距离或其他异步媒介上也可以通过可靠性建立信任。建立起的信任会让你克服合作道路上的不确定性。

建立信任

InnerSource重视书面交流-特别是在项目决策方面。 这是否意味着禁止面对面交流?

显然不是:书面交流在归档和可搜索性方面非常出色,而面对面交流则包含了更多的信息量。尝试抽时间去和这些人会面,如果可能的话,尝试用你最喜欢的饮料或食物满足他们。当你能听到他说话,当你能知道他的个性,那么远程协作将会变得更加容易。

避免拒绝

你有想要贡献的大型的功能吗?太棒了!如果你所有的工作都被浪费了,岂不是很恐怖?当项目团队已经在做了非常相似的东西,打算弃用该项目或觉得你提供的不适合他们的项目时,就会发生这种情况。这一挑战时经常发生的,许多团队关系都因没有事先对一个贡献是否适合项目形成统一意见而受到影响。

在进行改动和 pull requests 之前,先征得维护团队对用户/技术设计的同意,以使自己和维护团队都满意(且可能可以节省一些工作)。你必须了解维护团队希望你如何做到这一点,最好是向 Trusted Committer请教如何最好的讨论你的提案。

开源领域经过反复验证出的明智的做法是,如果你在考虑选择哪种方式讨论你的提案,你应该尝试选择书面方式。理想情况下,在将来关于你的贡献的讨论中,选择材料公开的,可搜索的和可永久链接到的文档来引用你的提案。

这种高阶的,早期的预先协议将节省时间,避免返工或被拒。

创建 pull request(拉取请求)

沟通畅通无阻

太好了,你已经熟悉了项目团队的方法,他们期待收到你的 pull requests 。那么现在有哪些陷阱在等着你呢?

首先,你与他们会比较少直接接触。其次,你不像团队在全职项目里所拥有的那样全面的的对项目的理解。你现在怎么最好地应付呢?

尝试细读团队的文档、聊天记录和代码工程,以提升自己。这与你和大多数人在使用流行的OSS项目时所处的情况类似,并且可能大多数人会发现自己处于这种情况。

就像在开源代码项目中一样,即使想自我解决也要询问项目团队有没有进展。你提出的问题和得到的答复将会帮助到在你之后遇到这个问题的人。确保你的通信最终收录在与项目紧密关联的可被搜索的文档里。如果您看到容易实现的优化点(如果尚未实现)可以实现上述目标,则可以尝试-非常有礼貌地-向项目的维护团队提出改进建议。有时,现状产生于纯粹的偶然事件,并保持这种状态,因为没人对此产生其他的想法或足够的关注。在这种情况下,欢迎提出改进建议。与更了解项目的人进行几分钟的对话,就可以解决问题,如果没完没了地讨论这个问题,对任何一方都没有好处。可以寻求帮助。

但是,有一个主要区别,它可以在将来为你和其他人带来好处:在几乎所有情况下,你都应该首选项目的官方交流渠道——可以是发邮件、聊天室、一个问题追踪器或类似的东西,具体取决于想要更同步的还是异步的方式,或交流中的不同需求。所有这些通常都有一个共同点,那就是它们都是基于文本的、存档的、可搜索的,且有稳定的链接——这意味着你的问题和答案会被记录下来,这些答案中链接的参考资料也会保持可访问性。通过这种方式,您可以从搜索中获得的这些被动记录的知识中受益,并带给未来的贡献者同样的好处。这种被动的文档甚至可以用来丰富“官方”文档,如果它恰好包含特别有价值的宝藏——比如专门创造的重要定义。

在工作时,如果发现缺少(或过时)的文档,请帮下一位贡献者进行更新你所发现的内容。维护团队通常很高兴收到现有文档的补充、更新或更正——你刚刚发现了另一个贡献的机会!(或者只是有礼貌地向他们提供有关您的经历以及对您有过帮助的反馈)。

编写代码

我们对代码样式,缩进等都有自己的偏好和看法,项目团队的项目也有这些偏好和看法。即使不是你通常会做的,即使项目的 _ “CONTRIBUTING.md”_ 中未指定,也要尝试调整并匹配这些偏好。如果不确定,你可以随时请教。不过,用户为某个功能或错误修复做出的贡献,就不适合引入新的构建或格式化项目代码的新方法。

提交 pull request

你已经完成了所有必要的工作,找出了所有问题和你正在贡献的项目的问题,离计划使用新功能的时间也越来越近了,并能尽快顺利地合并你的贡献。

你可以按照以下步骤,使 Trusted Committer和维护团队尽可能更轻松的进行审核和合并。实际上,这可能与你在自己的项目中为使更改能被接受而做的事非常相似。如果是这样就太好了,这对你来说自然而然!

测试和自动化

测试和自动化的基本作用是让 Trusted Committer 能在不需要你参与的情况下验证你的代码,并保证代码的可维护性。想象一下,你开发了某项功能,解决了某个难题,或者完成了某重要的性能调整,但是你的代码里并没有对这些进行清楚的说明(说明可能看起来不够通顺或者是错误的)。如果你用测试代码来解决这个问题(最好在测试代码的注释中说明测试的基本原理,编辑器将能自动地对测试代码做出注释),测试将保证你的代码的质量,即使到新的环境也是一样。要做到这些,你可以:

  • 为你的代码添加测试,以便即使在一段时间之后(当你去其他项目工作了或可能已经停止为该项目做出贡献时),其他人也可以很好的使用它。

    • 通常,项目会使用这些测试和代码对 pull requests 进行自动检查。尽量满足这些测试执行的标准。

  • 许多项目将提供项目构建和验证脚本,使你能够在本地测试你的更改。

    • 在打开 pull requests 之前,使用这些工具可以确保你的贡献能尽可能正常地工作。

    • 不得不检查易于修复的错误的有缺陷的pull request通常会让TC困扰 ,他们将不会修复你的代码而会叫你自己改,这可能会导致频繁的返工,导致 merge(合并)很慢。

    • 但没有人是完美的,尽你最大的努力,使用预先准备好的验证脚本(如果有的话),并使用 pull requests 来完成最好的尝试!

    • 如果你的 pull requests 仍然不可行,而你在尽了最大的努力之后仍然找不到原因:试着在 pull requests 的注释中突出显示这些,说明你目前对问题的理解并寻求帮助。

  • 别忘了最初是你自己的项目激发了你的贡献的动力, 创建一个包含了你的更改的共享项目版本,然后你自己的项目中试用它。

文档和可审查性

你得确保你的 pull request 所包含的所有文档更新都与你的改动有关。如果文档位于不同位置,请确保 你的pull request包含了这些文档的链接。

为了让 Trusted Committer 或其他审核者尽可能轻松地进行代码审核,请遵循以下提示: * 请确保你的 pull request 只包含你要解决的问题的相关更改。

  • 尽量避免超大型的提交、提交信息不明确的提交、大量文件、不连贯的修改(例如涉及多个主题)。

  • 明确说明这个pull request 的更改内容、更改原因、针对哪个issue以及引用了哪个设计文档(如果有)。

  • 如果 pull request 中有特殊的地方,请强调它并提供说明。这样可以更容易解决审阅者遇到的问题。

    • 同样的情况也适用于你不确定它是否可以实现或你的方法是否正确,那么请突出显示它并请求帮助理解。

    • 要有礼貌, Trusted Committer 也会礼貌的给出评审。

  • pull request 太广太大会使他们更难审查,所以他们需要更长的时间才能去接受它。

    • 如果你正在贡献一个更大的功能,将其拆分为多个 pull request 通常会有所帮助,这些请求按顺序提交、检查和接受。你仍然可以通过你提的issue将它们结合在一起。

      • 有些工具还具有 Draft/WIP pull request 功能,您可以使用这些功能来标记未完成和不完美的作品,并且仍然可以从产品团队的 Trusted Committer 那里获得早期反馈。

      • 这样一来,你可以确保你所做的一切能使项目团队一旦完成,就乐于合并(merge),并坚持“尽早发布,经常发布”的想法。

      • 项目团队的责任是营造一种氛围,使大家可以共享和讨论不完美的工作。 如果你不能勇于试错,你就无法创新,协作就会变得非常困难。

      • 试着在要求评审尽早审查和为评审提供有意义的更改之间取得平衡。

附加条款

其中一些资源可能需要付费。有时你的雇主有订阅权限,还有公立大学的图书馆也会提供查看权限。

Contributors