建立和管理开源项目的最佳实践

Posted 2023-03-06

技术标签:

【中文标题】建立和管理开源项目的最佳实践【英文标题】：Best Practices for Setup and Management of an Open Source Project 【发布时间】：2010-04-02 16:23:03 【问题描述】：

今年晚些时候，我想发布一个我一直致力于开源的 php 框架。我确实使用源代码控制 (SVN)，但它的基础非常有限。我是自学成才的，我自己开发，没有与大型团队合作的经验。我对什么可以帮助项目成功有一些想法，但我对一些细节很模糊。由于它尚未发布，我想尽我所能从一开始就设置正确的基础架构。为了设置和管理成功的项目，我需要了解什么？

我必须让它成功的一些想法（除了营销它）：

良好的文档和教程自动化单元测试和构建将更新推送到网站清晰的路线图错误跟踪与集成源代码管理保留代码的样式指南一致供社区获取的论坛支持、分享想法等。一个很好的示例应用程序框架让社区了解最新动态的博客保持向后兼容性尽可能

我的一些问题：

如何设置和自动化一个步骤提交测试提交生成 API 文档推送更新到网站流程？编辑：Ant 或 Maven 会是很好的候选者吗？如果是这样，您知道使用它们设置 PHP 项目的任何资源吗？我该如何处理（技术上）来自其他用户的提交？怎么能我确保这些提交必须在整合之前获得批准？有哪些陷阱？可以避免的方面项目社区？我宁愿有它像友好和乐于助人一样可能没有太多戏剧性。

我很想从您在这些方面的经验中学习。如果您认为我遗漏了任何重要内容，也请分享。您可以向我指出的任何资源（最好面向初学者）也将不胜感激。

【问题讨论】：

一次一个问题在这里是个好主意。在这一点上，关于自动系统设置的第一个问题可能是我主要关心的问题。无耻插件：openprojectguide.org 我正在那里写一些关于开源项目的启动和“维护”的博客文章，主要是从人的角度来看 【参考方案1】：

我刚刚开始参与社区项目，但我会就我所知道的给你一些建议。

如何设置和自动化一步提交-测试-提交-生成 API 文档-推送更新到网站流程？

我从来没有将它作为一个进程来实现。你可以有一个清单，甚至可能创建一些脚本来完成某些任务。我从来没有使用过任何可以自动上传的源代码控制，并且可以通过脚本来完成。大多数时候，都会涉及到一些网络交互。

在正式发布之前，您不想推送 API 更改。

编辑：工作环境

对于 PHP，大多数时候，我要么直接在服务器上编辑并在那里测试它，使用 beta.example.com 或类似的，然后推送到 example.com。您还可以在家用 PC 上设置 Web 环境（使用 XAMPP for Windows，或使用 Linux 上的标准 LAMP 安装）。您可能会在这里只使用您的存储库的镜像，因此您可以使用svn commit，或者任何适合您选择的 VCS 或 DVCS。

有趣的部分是使用不同的 PHP 版本进行测试。我自己没有这样做，但您可以使用 .htaccess 文件来运行不同的 PHP 二进制文件以对其进行测试。我不太确定最好的选择是什么。

我没有对 API 做太多，因为我从来没有创建过库，只是快速搜索一下就找到了http://www.phpdoc.org/。它看起来像一个成熟的项目，所以这可能是一个起点。

就创建版本而言，我通常会创建一个脚本，其中仅包含属于分发版的文件（它会过滤掉任何 VCS 文件，以及分发文件中您不想要的任何内容）。你可以在 linux 上围绕find 编写一个脚本（这是我大部分时间都在做的），或者可能有其他更好的选择。

我如何（技术上）处理来自其他用户的提交？我如何确保这些提交的内容在被整合之前必须得到批准？

这主要由错误跟踪器处理，并在版本控制系统中限制访问。通常，您和您允许的人可以对 VCS 做出承诺。其他用户可以提交补丁，但您可能会让某人查看补丁、测试补丁并提交。您可以将这些任务拆分为一个团队，或者将补丁分配给一个人并让他们完成所有工作。

就项目社区而言，有哪些可以避免的陷阱？我希望它尽可能友好和乐于助人，而不需要太多戏剧性。

我会确保尽可能对项目成员和社区保持积极的态度。会有一些分歧，会赶走一些人，但只要你有一个稳定的产品，可以满足大多数人的需求，我想这就是任何人都可以期待的。

【讨论】：

API 文档的要点。也许想要一步完成所有这一切的希望太大了，但您能否更详细地了解您是如何分多个步骤完成的？你用了什么工具等等？参见我上面的“工作环境”部分。【参考方案2】：

一个对我很有效的小建议：开始使用第一人称复数代词，而不是单数代词。也就是说，谈论“我们”和“我们”而不是“我”和“我”。它鼓励其他人在他们觉得自己是团队的一员时参与，而不是在他们觉得自己在为自己的自我扩张做出贡献时参与。

【讨论】：

这对我来说是一个公认的答案似乎很奇怪。它只回答了一个问题，甚至没有完全回答。哦，好吧，我不会记仇（抱怨） :)【参考方案3】：

你要做的最重要的事情就是吸引用户。没有用户，您将无法获得任何贡献和开发人员的帮助。因为开发人员首先是用户，然后他们决定扩展/修复他们使用的东西并可能成为贡献者。

所以要获得用户，你应该考虑

在项目页面顶部用一两句话描述您的框架的作用提及您的框架可以如何使用，在什么情况下最有用添加大量使用示例提及您的框架是稳定的、beta 版还是 alpha 版。这很重要，因为用户在开始使用之前需要知道这一点还提到你是否想继续改进它并继续努力——大多数用户不想使用一个被废弃的框架（还要记住，很多用户检查你的提交以查看你是否真的在工作就可以了 - 如果您对存储库的最后一次提交是几个月前，那么您并没有真正致力于它，所以作弊是不可能的）

如果您掌握了所有这些，并且人们开始提交补丁，您可以使用补丁工具将这些应用到您的源代码中。根据您的版本控制系统，您可以使用 GNU 补丁、版本控制附带的差异/补丁工具，或者甚至可以帮助您解决此问题的 GUI 工具。 SVN 还没有补丁工具，但是 'svn diff' 会创建一个补丁文件，然后你可以使用 GNU 补丁工具来应用它，或者如果你使用 TortoiseSVN，右键将补丁文件拖到你的工作副本中并让 TortoiseMerge 为您应用它。

以及如何最好地与社区打交道：

及时回答问题，不要等待超过两三天才能回答问题尽量表现友善，即使面对不高兴和愤怒的人。只有当他们继续打扰时，才告诉他们（如果可能的话，还是以一种很好的方式）去别处始终在邮件列表中保留有关项目的讨论。您不想一遍又一遍地重复相同的讨论 - 如果您有一个邮件列表，只需在重新开始讨论之前将用户指向存档

您应该观看“How Open Source Projects Survive Poisonous People (And You Can Too)”讲座——它真的很好，它告诉您很多关于如何处理不仅是“有毒的人”，还包括如何处理所有参与您项目的人。

【讨论】：

【参考方案4】：

我想补充一点，您应该让您的用户尽可能轻松地运行整个程序并修改代码 - 这些“高级用户”可以“转换”为开发人员或至少是发送更小的补丁。

【讨论】：

【参考方案5】：

不要试图自己做所有事情 - 对于开源项目，有几个托管服务提供商可以解决大部分问题。我推荐 codeplex 或谷歌代码。

设置构建脚本将在一定程度上取决于您设置的平台，但一般来说，一旦您开始使用任何类型的构建脚本，就可以轻松地将所需的任何工具添加到脚本中。

如果你真的需要你描述的一步过程，你需要一个构建服务器。我使用 TeamCity，我已设置它来监视 svn 中的任何更改，并在签入某些内容时触发构建/测试。构建服务器通常能够执行您放入构建脚本中的任何步骤。

【讨论】：

TeamCity 看起来很有趣。您将它用于 PHP 项目吗？你知道有什么类似的东西可以比较吗？我没有将它用于 php，但它不是特定于语言的。它有一个命令行运行器以及 msbuild、ant 等，所以只要你有某种构建脚本可以在服务器上运行它就可以工作。 CruiseControl 也很受欢迎，虽然我自己没有使用过。【参考方案6】：

阅读 Git 作为 SVN 的替代方案

Github（托管 symfony 和 PHPUnit 等）中的免费公共存储库/错误跟踪器/wiki/fork 社区 “我如何处理（技术上）来自其他用户的提交？我如何确保这些提交在被集成之前必须得到批准？” - 使用 Git，提取您/您最近的团队发现的内容对 master 分支最感兴趣

一致的 API

受到其他公共 API 的启发：s 仅在主要版本中发生变化可以猜测的

对用户和开发者都很有趣

明确的目标（您的路线图 - 出色）有用，与其他所有可用的相反易于使用，但仍然不够容易编写/维护自己

您可以查看 Ant 或 Phing 来构建您的项目。在构建中包含CodeSniffer，您将节省检查基本格式错误/差异的时间。

这些都是技术技巧，关于软的部分...尊重人类，充满兴趣并过度对他们的贡献感到兴奋，让他们觉得他们没有浪费他们的时间。这对我很有吸引力。

【讨论】：

【参考方案7】：

在Producing Open Source Software 上查看 Karl Fogel 的书。它可能包含您所要求的一切。

您还应该计划让社区参与进来。我建议阅读 Jono Bacon 的社区艺术 [http://www.artofcommunityonline.org/]。