• 项目

2018 年 10 月

33 卷，第 10

此文章由机器翻译

必备.NET-参与 Microsoft 开放源代码软件项目的方式

通过Mark Michaelis |2018 年 10 月

下面是一个事实：Microsoft 托管在 GitHub，包括.NET 编译器平台，也称为"Roslyn"具有多达 4 万行代码等一些相当大的大约 2,000 开放源代码软件 (OSS) 存储库。很多开发人员的代码将更改提交到数以百万计的计算机运行的项目可能会令人望而生畏。幸运的是，无需专业的博士学位的编程语言和编译器，使您标记在 Microsoft OSS 项目上。有机会来推动的范围很广的难度和体验，从初级用户到方面的专家。

我收到了我开始在 2018 年 3 月中使用.NET Core 团队合作，添加一组新的 Api。我就能够跳转在板上，由于我在 Microsoft，特别是与项目经理 Kathleen Dollard 的连接。在我真想知道，"难它会给人不是很好地连接 microsoft 参与此计划？" 记住此问题，我决定进行一些研究并找出。在本文中，我将探讨推动业务的 Microsoft 操作系统和究竟是于新用户若要获取所涉及的主题。

入门：文档和拉取请求评审

可能的最佳去处是文档。如果你导航到任何.NET 文档页面 (例如， bit.ly/2LAv7hA) 可以看到，没有请求反馈，页脚中所示的每个页面的底部图 1。

提交的建议和文档的更改
图 1 提交的建议和文档的更改

从此处你可以单击"产品反馈，"提交新问题，或浏览和搜索现有问题。更为可喜的是，第二个按钮，直接转到您的浏览，因此，可以创建一个 GitHub 问题或导航到的文档源代码本身的特定页的 GitHub 问题列表 (如github.com/dotnet/docs) 直接解决该问题。记录问题所需的工作比容易频繁，只需更新文档和提交拉取请求 (PR)。

我所直接接触团队成员和它们强调所有提交都都欢迎，即使拼写和语法的更正。这些更改可能不会令人兴奋，但它们会使成功的 API 和一个不成功之间的差异。

此外，文档团队是最快响应提出的问题和 Pr，分配给每个区域对轻微地址贡献的人员之一。一个原因文档编辑很简单：它通常不需要您来克隆存储库提交更改。相反，您可以使用 GitHub 基于 Web 的编辑 UI，它能自动使用分叉并为您提交拉取请求。

PR 评审也是参与的重要方法。每个项目需要拉取请求反馈和 Microsoft 团队是感谢 PR 评审发布内容。我知道我已经非常感谢 — 和学习从 — 我已提交到.NET 的工作原理的评审。为我的最大经验是时间的，我不能在跳转，并随意或执行其他操作之间薄片中做出了重要贡献。在此级别的代码需要经过认真的考虑，仔细地实现和重要的协作。最后，我很感谢拒绝的 Pr 和接受的 Pr。PR 评审是一个很好的步骤，并帮助解决开放源代码开发。

第一次可接近问题

为准备采取行动上多个文档，Microsoft 提供了一些指导。使用"第一个问题"等描述符标记，并且容易很适合不熟悉游戏开发人员的问题。Microsoft 甚至要求活动项目成员，为了避免快要结束的版本中，直到第一次可接近问题，因此将更容易问题提供的熟悉的开发人员保持到项目和降低复杂性栏的入门知识。此外，第一次可接近频繁问题描述了如何查找问题的文档链接，而不是新的开发人员在尝试查找特定缺陷大海捞针 flailing 的是大型存储库。Roslyn 团队，例如，一个很好的第一个问题必须包括：

  • 解决方法是很有必要的文件的链接
  • 测试需要转到标识
  • 开始使用 Roslyn 的设置说明
  • 常规发布内容策略

倾向于选择来自新用户的贡献承诺可以扩展到如何接受 Pr。对于标记为"良好第一个问题"的 Pr，Microsoft 不提供首选项设置为新的参与者，Pr 接受通过来自现有 contributors （参与者）。更重要的是，Microsoft 职员标记为"良好第一个问题"的问题将直接回答问题的人员而言，若要解决此问题。该位获得详细可以是指导的在参与的第一个阶段中重要。

很明显，Microsoft 转去获取第一次参与者参与。Roslyn，例如，是一个复杂、 4 万行代码库不是重点所在。通过具有吸引力的新参与者，Microsoft 的 OSS 工作使外部开发人员组成的活跃社区。

定期撰写

接受在第一个拉取请求后，可能要执行更复杂的问题和功能。有"想要帮助"和"最，无法用于 grabs"等来表示问题可能是很好的目标为社区的问题标记 — 尽管不一定适用于第一个计时器。(请参阅最多为 grabs.net来浏览项目和相应问题的列表标记此类与第一次可接近或想要的帮助。) 标记为使用这些标记可能的问题涉及更多的工作或更深层次的项目不是可以提供主体;但是，它们是定义完善，并且不需要与项目团队的广泛协作。但是，还有您最好按照定义工作流：

  • 应与团队和路线图，以避免被拒绝的时间范围内讨论了超过 bug 修补程序级别的发布内容
  • 发布内容应该是针对主 — 不是针对一个实验性功能分支
  • Pr 必须与主分支的提示轻松合并
  • Contributors （参与者） 应确保登录参与者许可协议 (请参阅cla2.dotnetfoundation.org)

如所料 Git 具有丰富经验的开发人员，务必在本地分叉 （克隆到您的计算机） 中工作，并提交 PR 通过要考虑的代码当然，您可以创建本地，一个分支但提交 PR 时您将会提交到 master。

有少量的编程和工作流指南，需要注意。首先，是要考虑的编码样式。尽管可找到 C# 编写代码处的样式bit.ly/2woQv3u，常规摘要是为了遵循标准的现有文件。即使现有文件不同于有案可稽的标准，这是，则返回 true。这意味着要编码整个文件 （或添加为其已存在没有优先顺序在文件中的项），直到该准则是简单 — 遵循该文件的其余部分的示例。即使没有优先级，但是，没有仅有 16 位项 C# 编码样式文档中列出这些都特别令人惊讶。这些项包括：

  • 在自己的行上的大括号
  • 每空格缩进 （而不是选项卡）
  • 常量局部变量和字段的内部私有字段和 PascalCasing _camelCase
  • 避免这种情况。除非要求
  • 始终指定可见性 （即，使用专用即使该成员的默认值为专用）
  • 避免多个空行分解代码
  • 分配的类型明显时只能使用 var (请参阅itl.tc/UsingVar)，除了 Roslyn 项目，其中使用 var 无处不在
  • 指定在类型声明顶部的字段

通常情况下，您会发现.editorconfig (请参阅editorconfig.org) 为每个目录，强制执行这些标准设置文件。请务必使用该文件以确保您遵循的准则并避免阻止 PR。

对于那些在 Visual Basic 中编写代码，请按照精神和 C# 指南的目的。

尽管不在列表中所述，单元测试是质量的生成所需级别的关键。

设计帮助

某些存储库，如语言、 CoreFX 和 Dotnet CLI 需要明显更高级别的经验和专业知识，并在这种情况下，使用不同的进程。使用这些库的入口点是在讨论级别而不是代码级别。直接提交到这些库使用的新功能或语言关键字的代码 PR 不太可能成功。

设计过程通常可见时，它不是 free-for-all。事实上，甚至不使用征求建议书启动这些存储库的提交。(签出的 C# 语言征求建议书文件夹在bit.ly/2BVUbjf为仔细查看当前正在考虑的主要功能。) 相反，如果你想要推荐一种功能，您首先提交问题并标记与"讨论"标签。如果讨论项目达到一定程度的一致性，以便进一步评估应被视为，它们被选取在语言设计会议，这样又知悉的进一步讨论、 试验和脱机设计工作。征求建议书本身 — 不会被终结的功能，然后提出语言设计团队的成员。

尽管过程用于打开反馈，并非每个人都可以只需进行更改，但他们选择。分发数量，以及更改的影响是太好不严格控制 （非常类似于 Linus Torvalds 具有与 Linux 一起的控件）。最后，该项目是仍开放源代码。如果您希望能够自由地更改需要的地方的任何方式中的代码，只需将存储库分叉，并开始。

这种方法是进行协作处理代码实现开始前的重要方法。即使这样，可能会变化很长一段是一个单独的分支中，而它们进行编程 （并反复重新进行编程） 和计算。社区中决定什么某事物的形状将会至关重要。打开要讨论的问题，注释，并提供使用现有的征求建议书的反馈提供给团队的直接访问。

你将注意到，导致可运行的域范围从简单到极其困难。将方法或类添加到 API，例如，是一回事，但添加新的语言关键字完全是其他内容。

提交 PR 后发生的情况

在 2018 年 4 月 Roslyn 团队意识到他们具有对处理所有具有已提交的 Pr 方面滞后。与 Pr 后发生的所有更改，很可能，其中一些将不再相关。若要解决此问题，Microsoft 单步执行和分配给每个项目的人员。这是为了响应所有未来的 Pr 以确保将放入的工作是更有可能会成功。向该工作，他们落实到位，Pr 的以下分类：

  • 项目主管已审批：已批准的 Pr 是从分配的同学或教练项目团队提高成功被采用的机会，帮助将拉取请求合并到基本代码。教练可确保社区成员已同时参与，这将执行 contributors （参与者） 在三个工作日内如果由于任何原因拒绝拉取请求。
  • 挂起的讨论：有时非常重要的问题突然出现 — 单元测试是缺少、 目的不明确，或代码无法显著满足这些指导原则。在这些情况下，项目领导会引发与社区参与者，确定应该做什么的问题。潜能，参与者可以在两周内执行后续操作。此外，在该分组中的 Pr 需要及时了解代码基在此期间。
  • 已拒绝：拉取请求不符合的项目愿景、 涉及巨大的风险或不能成功解决优先级。在这种情况下该潜在顾客将拒绝该 PR，清楚地确定问题。虽然可以重新提交拉取请求，它将需要进行重大更改或重新编写。

总结

有时，您可以观察中的行为会打开源代码项目组成的远低于体面而主动的标准。这可能包括原始、 某事或反复失败侦听对立视图的参与者。它还包括无法接受 Microsoft OSS 项目最终仲裁器作为 Microsoft 的角色、 重复垃圾邮件存储库或否则会中断协作过程的参与者。任何人都不能遵循常规 civility 的规则将发现自己阻止从存储库 （并且返回下具有相同伪行为不会使您任何进一步）。Microsoft 致力于为所有，使参与积极的体验和强制行为准则是上述承诺量的核心。

我鼓励您查看 Microsoft 开放源代码行为准则处bit.ly/2wmAYlB。此外可以查看在其关联的常见问题解答bit.ly/2NwNNRa。

在我的经验，如何方法对 Microsoft OSS 进行更改取决于很大程度上生成想更改您关注的内容。我希望大多数人将对，从而促进是有缺陷或缺少的功能的窗体中的问题。最初，触发器可能缺陷或文档，并希望修复其他读取器中的问题。或者，也许你正在努力 Xamarin 代码库中并发现您希望重写的方法不虚拟的因此提交 PR 以使其此类。

有些人将需要在更大的挑战。使用.NET Core，我都已通过这一事实 （仍然） 没有一个可以轻松地接受命令行自变量并将他们解析到从中我可以访问我的程序中的值的强类型对象的命令行分析器已 astounded。这是提示我开始与 Microsoft 的 Jon Sequeira （Dotnet CLI 为编写的命令行分析器） 人员协作来构建此类分析器此得。唉，代码仍然不太稳定并对我们进行项目太休闲我们参与开放源代码。但愿不会太长之前此项目是我们为公开，因此也可以受益于参与度的 OSS 社区可以打开。在此期间，如果您有很长时间才能将专用和对我们的分析器项目感兴趣，将一封电子邮件发送给 Kathleen 或与我们可以推断出获取涉及一种方式。并且，是的我只是引入了另一种方式参与 — 自发之前代码是公共的。

Mark Michaelis 是 IntelliTect 的创始人，担任首席技术架构师和培训师。他一直是 Microsoft MVP 在近二十，和 Microsoft 区域总监自 2007 年以来。Michaelis 还是多个 Microsoft 软件设计评审团队（包括 C#、Microsoft Azure、SharePoint 和 Visual Studio ALM）的成员。他在开发人员会议上发表演讲，并撰写了大量书籍，包括最新"Essential C# 7.0 （第 6 版）"(itl.tc/EssentialCSharp)。可通过他的 Facebook facebook.com/Mark.Michaelis、博客 IntelliTect.com/Mark、Twitter @markmichaelis 或电子邮件 mark@IntelliTect.com 与他取得联系。

衷心感谢以下 Microsoft 技术专家的帮助进行协作和对本文的审阅：Kevin Bost (IntelliTect)、 Kathleen Dollard、 Neal Gafter、 Sam Harwell、 Immo Landwerth、 Jared Parsons、 Jon Sequeira Bill Wagner，Maira Wenzel

在 MSDN 杂志论坛讨论这篇文章