Get best of the week

开源指南：启动一个开源项目



译者序


几个月前，我在Github上偶然发现了“开放源代码指南”链接，并且无法退出。在一周的某个地方，我仔细阅读了所有10个部分。当然，我已经对开放源代码有所了解：我阅读了各种文章（例如，“了解开放源代码”），在我的工作中使用了这些项目，向社区提出了问题，报告了错误，发现了问题，甚至做出了笨​​拙的尝试。然后至少改善文档。当然，我对这些共享软件和软件使用知识的人深感兴趣。但是，开源的概念相当模糊和零散。并且本文增加了清晰度。

此外，我计划以这种格式启动几个项目，希望得到社区的支持，并伴随着许多担忧和疑虑，本文再次帮助我确定了意图并提出了切实可行的步骤。

无论您对开源的态度如何，我认为您都会在这10篇文章系列中找到许多有趣的想法和事实：组织，心理，法律，道德和技术。

我让这个非程序员阅读本文，他们说他们理解一切。在本文的标题中，我故意将“源代码”与“代码”放在一起，因为该主题不仅与程序员相关，而且与开放项目格式的几乎所有智力活动都相关。

该手册本身也是开源的，已经被翻译成14种语言。很荣幸添加俄语主题和第一篇文章的翻译。我计划每周继续翻译文章。如果有人想连接，这里是存储库：开源指南。

如果突然有人从文章标题（插图+俄语名称）开始需要屏幕保护程序，则该代码位于codeandbox.io上。

术语选择


对于翻译中的缺陷，我事先表示歉意。在俄罗斯，一些看似平庸的用语并非易事。例如，为了贡献，拉动请求，发布问题，我经常将其翻译为“参与项目，提出更正和提出问题”。到目前为止，我没有使用英语开源。我已经发表了评论，并发送了Github术语词典的链接。我不喜欢那里大量的音译。如果您将所有这些ish，pullrequest，push，pool，fork放入本文中，那么对于那些不使用Github的人来说，这将变得难以理解。

是的，问题可能是问题，任务，错误报告，句子等，而且很难找到一个俄语单词来传达所有这些含义。但是英文单词issue也没有特别广泛的含义，只是Github的创建者和用户赋予了它如此广泛的意义。如果我们用“在Github上提问”一词的意思是这个问题可能非常不同（错误，问题，寻求帮助，任务等），那么“问题”一词将和谐地替换“问题”一词。另外-推送-发送，拉取-接受，派生-分支等重要的不是单词本身，而是我们同意输入的含义。英国人首先遇到了有关Github的术语问题，还必须首先阅读该系统框架内所有可能含义的描述。同时，对于没有与Github合作的最大人数，我将明确性作为优先事项。无论如何，都是在选择术语，整个翻译过程像原始版本一样都是开放源代码的，拉动查询也是如此，而且都是开放式的。


: ?
«open source»?
?
Open source — ?

open source ?



open source

README






, ( ) !






: ?


那么，您是否正在考虑启动开源项目？恭喜你！全世界感谢您的参与。让我们谈谈什么是开源以及人们为什么这么做。

开源是什么意思？


打开项目代码后，这意味着任何人都可以出于任何目的自由使用，研究，修改和分发您的项目。这些权限是通过开放源代码许可证授予的。

开源的优点是它减少了选择程序和协作的障碍，使人们可以快速分发和改进项目。另外，相对于封闭代码，它使用户能够控制代码。开源软件公司（软件）可能会雇用某人来对该软件进行改进，而不是仅仅依靠开源供应商的决定。

自由软件所指的项目与开源软件（the open-source）。有时，您可能会发现这些术语的组合：“自由和开源软件”（自由和开源软件FOSS或自由，自由和开源软件FLOSS）。自由和自由一词在这里表示“自由”，而不是“自由”。

人们为什么要公开工作？


头像我从开放源代码获得的最大回报之一就是与其他面临与我同样问题的开发人员建立的关系。
@ kentcdodds，“我对进入开放源代码有多大的兴趣”

个人或组织打开其项目源的原因很多。这里是其中的一些：

  • : Open source . , Exercism, 350 .
  • : Open source , . -. WordPress, , b2.
  • 透明度：任何人都可以检查开源项目中的错误和不一致之处。即使在州一级，透明度也很重要。例如，保加利亚政府和美国立法规定了银行，医疗保健和安全软件（如Let's Encrypt）等行业的透明度。

开源不仅适用于软件，还适用于其他所有方面：从数据集到书籍。在GitHub Review中，您可以获得有关什么可能过于敏感的更多想法。

开源免费吗？


免费开源是其最大的好处之一，但不仅是它的唯一好处，而且还是其综合价值的副产品。

由于开放许可意味着几乎任何人都可以使用，修改和分发您的项目，因此在大多数情况下，这意味着免费。因为如果您要收费，那么人们会绝对合法地下载并免费使用该项目。

因此，大多数开放源代码项目都是免费的，但是开放源代码的定义中并未包含此内容。有多种方法可以通过双重许可或有限功能对开源项目进行间接收费，但它们符合开源的官方定义。

我应该启动我的开源项目吗？


简短的答案是肯定的，因为不管结果如何，启动项目都是了解开源如何工作的好方法。

如果您以前从未运行过这样的项目，您可能会担心：“人们会怎么说？”，“如果没人能注意到他怎么办？” 如果您对此很熟悉，请放心，您不是唯一的一个！

像任何创意作品一样，无论是写作还是绘画，开源都会在与世界分享之前引起兴奋。但是改善它的唯一方法是练习，即使您没有观众。

如果您尚未决定，请花些时间考虑您可能的目标。

目标设定


目标将帮助您决定要做什么，放弃什么以及需要外部帮助的地方。问问自己：“我为什么要打开这个项目？”。

这个问题没有单一答案。一个项目可以有多个目标，也可以有不同目标的不同项目。

如果您的目标只是展示您的工作，而无需合作，则可以编写README文件。另一方面，如果您对助手感兴趣，则应该花时间编写易于理解的文档，并照顾好初学者。
头像 UIAlertView … open source. GitHub. , , . , - . .
mavris@mavris, « : Open Source »

随着项目的发展，您的社区将不仅需要代码。回答问题（问题），代码验证，传播有关您自己的信息-所有这些都是开源项目的重要任务。

尽管花费在非编程任务上的时间取决于项目的规模和规模，但是您应该准备自己解决问题或为此寻找助手。

如果您是启动开源项目的公司的成员，请事先确保您拥有内部资源来进行开发。指派一名启动后的支持人员，并确定如何在社区内分配任务。

如果您需要专门的预算或人员来推进，操作和支持该项目，请尽快进行讨论。
头像当您开始一个开源项目时，组织中的管理流程必须考虑到围绕该项目形成的社区的贡献和能力，这一点很重要。即使在关键方面也不要害怕让外部人参与，尤其是在他们积极参与的情况下。
@captainsafia，“ Che，您要打开项目代码吗？”

参与他人的项目


如果您的目标是了解如何与他人互动以及开源如何工作，请考虑参与您使用和喜爱的现有项目。您的参与可能是诸如拼写错误和文档更新之类的简单事情。

如果您不了解如何开始参与其他人的项目，请查看我们的指南如何参与开源项目。

开始自己的开源项目


没有完美的时机来打开您的工作源。您可以在构思阶段，工作过程中或关闭几年后将其打开。

通常，只要您有足够的信心向陌生人展示您的作品并获得他们的反馈，就可以开源。

每个项目，无论您决定打开源代码的哪个阶段，都应具有以下文档：


它们将帮助您传达期望，接受其他参与者的更改，并保护包括您自己在内的所有合著者的合法权利。这大大增加了积极体验的可能性。

如果您的项目在github上，并且将这些文件放置在具有推荐名称的根目录中，则github将识别它们并将其自动显示给读者。

许可证选择


开源许可证可确保其他人可以使用，复制，修改和更改您的项目，而不会造成任何后果。它还可以保护您免受不愉快的法律情况的侵害。启动开源项目时，必须启用许可证。

法律工作并不容易。但是有个好消息：您可以复制现有许可证并将其放置在存储库中，在一分钟内保护您的辛苦工作。

MIT，Apache 2.0和GPLv3是最受欢迎的许可证，但是还有其他选择。

在Github上创建新项目时，可以选择多个许可证。通过选择一个开放源代码许可证，您将使您的项目打开。

选择一个许可证

如果您对开放源代码的法律方面还有其他疑问或疑虑，我们在此处进行了描述。

README的汇编


README文件（“自述”）不仅说明了如何使用您的项目，还说明了为什么它很重要以及用户可以做什么。

尝试在自述文件中回答以下问题：

  • 这个项目做什么？
  • 这个项目有什么用？
  • 我该如何开始与他合作？
  • 如果需要，我可以在哪里获得帮助？

您可以在README中指定：如何参与项目，其目标是什么，谈论许可证和作者身份。如果您不打算接受别人的进步，或者他还没有准备好竞选，那就写下来。
头像好的文档意味着更多的用户，更少的帮助请求，以及更多的协作者。（...）请记住，您的用户不是您。这些人可能是有经验的人-与您的人截然不同。
@tracymakes，“写，以便读到你的话（视频）”

有时，人们由于认为项目尚未完成或不想接受其他人的改进而推迟编写README。但这只是写出来的一个好理由。

为了获得启发，您可以阅读“制作自述文件”指南或自述文件模板。

当您将README文件添加到项目的根目录时，github会自动在存储库主页上显示该文件。

为参与者编写指南


CONTRIBUTING文件将告诉您的听众如何成为项目的成员。例如：


除了技术细节以外，CONTRIBUTING文件还可以用来表达您对他人参与的期望。例如：

  • 您正在等待什么样的参与？
  • 您对项目开发的计划和愿景
  • 参与者如何（和不能）与您联系

您热情友好的语气和参与的具体建议（例如编写文档或创建网站）对于吸引新移民从事项目至关重要。

例如，Active Admin使用以下单词开始其参与指南：
首先，我们要感谢您考虑参与Active Admin的开发。像您这样的人使Active Admin成为了一个很好的工具。

在项目的早期阶段，您的CONTRIBUTING文件可能很简单。您应该始终解释如何报告错误和填写问题，并描述编辑成员的技术要求（例如测试）。

随着时间的流逝，您可以补充常见问题的答案。因此，越来越少的人会一遍又一遍地问你同样的事情。

为了使编译CONTRIBUTING文件更容易，请查看@ nayafia的协作指南模板或Mozilla的“如何编译文件CONTRIBUTING.md”。

链接到README文件中的CONTRIBUTING文件，因此会有更多人看到它。如果将CONTRIBUTING.md文件放在项目的根目录中，那么当有人打开新问题（问题）或向项目添加编辑内容（拉请求）时，github会自动引用该文件。

协作指南

制定行为准则


头像当项目所有者粗鲁地解释一些事情或用户问一些基本问题时，我们所有人都会遇到不愉快的情况。（...）行为守则成为易于参考的文件，并说您的团队非常认真地进行建设性对话。
@mlynch，使开源成为一个更幸福的地方

因此，行为准则为您的项目参与者设置了基本行为准则。如果要为公司或社区启动项目，这尤其重要。行为准则有助于在社区中建立健康，建设性的行为，从而减轻您作为项目负责人的压力。

查看更多详细信息：《行为准则-指南》。

除了描述如何您希望参加者的行为，行为规范也解释给谁以及何时适用，如果违反会发生什么。

与许可证类似，您不必自己编写代码，但是可以复制现有选项之一。会员协议用于超过40,000个开源项目，包括Kubernetes，Rails和Swift。无论使用什么代码，都应准备在必要时应用它。

将CODE_OF_CONDUCT.md文件放在您的项目的根目录中，以便例如从README中查找和链接该文件变得更加容易。

为项目命名和品牌化


品牌宣传不仅是醒目的徽标和令人难忘的名称，而且还是您如何谈论项目以及传达给谁的信息。

选择正确的名字


选择一个易于记忆的名称，理想情况下可以给出项目实质的想法。例如：


如果您的项目是对现有项目的补充，则使用其名称作为前缀，这将有助于了解您的项目在做什么。例如，node-fetch将Node.js带到“ window.fetch”。

选择清晰。双关语可能很有趣，但您可能会想到其他文化背景的人，或者与您可能不懂笑话的人相比，经历不同的人。您的潜在用户可能是将与您的上级讨论您的项目的公司的员工。不要同时使它们脸红。

名称冲突


检查同名的开源项目，尤其是如果您使用相同的语言或生态系统。如果您的名字与一个受欢迎的现有项目相匹配，您可能会引起听众的困惑。

如果打算启动网站，Twitter或任何发布平台，请确保所需的名称在此处是免费的。而且，最好立即保留这些名称，以使您安心，即使您尚不打算使用它们。

确保您不侵犯任何公司的商标。将来，她将可以要求您关闭项目，甚至提起诉讼。这是不合理的风险。

您可以在全球WIPO品牌数据库中检查品牌冲突。如果您代表公司进行项目，那么法律部门可以为您提供帮助。

最后，对您的项目名称进行快速Google搜索。人们能够轻松地在上面找到您的项目吗？还是在此请求上出现了不良情况？

您的编写方式（和代码）也会影响您的品牌！


在项目的整个生命周期中，您将编写很多内容：自述文件，指南，社区文档，问题的答案，甚至是新闻通讯和邮件列表。

无论是正式文档还是常规信息，您的写作风格都是该项目品牌的一部分。考虑一下您在观众面前的灯光，以及您是否选择了正确的语气。
头像 , , . , , , , .
@janl, CouchDB, « Open Source»

友好和礼貌的语言将为新参与者营造一种愉快的氛围。另外，请注意表示的简洁性，因为对于许多读者而言，英语可能不是母语。

不仅您所写的文字，而且代码的样式也可以成为项目品牌的一部分。Angular和jQuery是两个具有严格样式和建议的示例项目。

刚开始时无需编写样式指南，无论如何，您可能希望在项目中包括不同的样式。但是您必须事先了解，您的编写和代码风格将吸引某些人并将其他人赶走。项目的早期阶段提供了创建先例的机会，从中可以以所需的形式发展项目。

开始之前的清单


您准备好打开项目了吗？这是一个可以帮助您的清单。选中所有项目后，单击“发布”并称赞自己。

文献资料


  • 项目中有一个开源的LICENSE文件
  • 该项目具有基本文档（README，CONTRIBUTING，CODE_OF_CONDUCT）
  • 这个名字很容易记住，给出了项目实质的思想，不与现有项目冲突并且不侵犯商标。
  • 问题列表是最新的，组织良好且带有标签的。

编码


  • 该项目使用约定的代码约定和函数/方法/变量的友好名称
  • 明确注释了该代码，并记录了意图和特殊情况。
  • 在修订历史，问题（问题）和修订请求（拉动请求）的历史记录中，无处没有敏感数据，例如密码或其他非公开信息。

人


如果您是私人个人：

  • 您与法律部门进行了交谈，并且/或者了解了您公司的知识产权规则和开源政策（如果您受雇于某处）

如果您是法人实体：

  • 你跟法务部谈过了
  • 您是否有启动和推广项目的营销计划？
  • 已任命负责与社区进行交互的人员：回答问题，检查请求请求并将其附加到项目中
  • 至少有两个人对该项目具有管理权限。

你做到了！


祝贺您打开第一个项目的源代码！不管结果如何，全民参与对社区都是一种礼物。每个提交，评论和修订请求都是一个为您和他人学习和成长的机会。

More articles:


All Articles