如何或多或少地为开源做出贡献

I’ve been trying to spend some of my free time outside of work contributing to open source over the last year, and thought I’d write a little about some lessons I’ve learned. Hopefully, they can help you too!

在过去的一年中，我一直在尝试将业余时间用于开放源代码的贡献，并认为我会写一些我学到的课程。 希望他们也能为您提供帮助！

首先，为什么？ (First Off, Why?)

I just want to start off by saying that contributing to projects can be super rewarding. Maybe there’s this weird bug in a node module that you use at work that you’ve built a fix for in your own application. If you can find a way to move that fix into the module, not only are you being a good open-source citizen by not just consuming that module (at no cost to you or your company, but with all of the utility), but you’re also giving back time and energy to a tool or library that has saved your company both the time and resources not having to build themselves.

我只想从一开始就说对项目做出贡献是非常有益的。 也许您在工作中使用的节点模块中存在这个奇怪的错误，而您已经在自己的应用程序中为其构建了修复程序。 如果您找到一种将修补程序迁移到模块中的方法，那么您不仅会成为一个好开源的公民，不仅会消耗该模块(对您或您的公司免费，而且会使用所有实用程序)，而且您还可以将时间和精力回馈到工具或库上，从而节省了公司不必自行构建的时间和资源。

You also can feel good about yourself knowing that every other person who uses that module in the future will be using your contribution! And maybe in 2150, when all software on the internet relies on that module (you know, like left-pad or something), you will truly have reached immortality and cheated death, living on in the electrical signals and wires of the networked world, like some 90s idea of some cyber god/entity. Anyways, where were we? Oh yeah, making some PRs on GitHub.

您也可以对自己感到满意，因为知道将来每个其他使用该模块的人都将使用您的贡献！ 也许在2150年，当Internet上的所有软件都依赖于该模块时(您知道，就像左键盘之类的东西)，您将生活在网络世界的电信号和电线中，确实达到了永生不朽的状态，就像90年代某些网络神/实体的想法。 无论如何，我们在哪里？ 哦，是的，在GitHub上进行了一些PR。

There was a really amazing podcast on Maintainer’s Anonymous with Maggie Appleton discussing open source as a gift economy that discusses how open source can be viewed outside of a market economy or just a water faucet of endless free packages. It resonated with me as motivation for why contributing is one good way to pay back the benefit you (or your company) has received from open-source software. Having your company sponsor maintainers of open source projects your product depends on is an even better form of reciprocation (maintainers gotta eat), but that’s for a different blog post.

在维护者的匿名与Maggie Appleton的讨论中，有一个非常了不起的播客， 讨论了开源作为一种礼物经济 ，讨论了如何在市场经济之外或仅仅是无休止的免费包装的水龙头之外观看开源。 之所以引起我共鸣，是因为为什么贡献是一种偿还您(或您的公司)从开源软件获得的收益的好方法的动机。 让公司赞助您的产品所依赖的开源项目的维护者是一种更好的互惠形式(维护者必须吃)，但这是另一篇博客文章。

旅程 (The Journey)

开始之前应该知道些什么？ (What should I know before I get started?)

If you take one thing away from this, remember to treat other projects as you would a house that you’re a guest in. If some rando from the internet came to your house, was rude to you, and demanded you let them make changes to your house, it’d be totally reasonable to kick them out.

如果您采取其他行动，请记住将其他项目视为您待客的房子。如果互联网上的一些兰多来到您的房子，对您无礼， 并要求您让他们进行更改到你家，把他们赶出去是完全合理的。

“But I’m totally a chill person, I would never come across that way.”

“但是我完全是一个冷酷的人，我永远不会遇到那种情况。”

And maybe you are, but to expand upon the guest in someone’s house theme, imagine you visit a friend’s house and upon entering walk straight past an area full of shoes and straight into their living room. Your host is a little annoyed and asks that you take off your shoes before walking around their house. But you wear shoes in your house all the time, so, not a problem, right? The problem is you’re not in your house — you’re in their house and so far you’ve already started your visit on the wrong foot, or shoe, or sock, or… whatever. Just because you think you’re being a good guest doesn’t mean you are by your host’s standards. What constitutes “not being a jerk” to you might not be the same for them. If only there was a way your host could’ve conveyed how they expected you to behave while you’re in their house…

也许您是，但为了扩大访客在某人的房屋主题中的想象力，想象您访问了朋友的房屋，并进入步行区，穿过一个鞋类繁多的区域并直接进入他们的客厅。 您的房东有点恼火，要求您在他们的房子周围走动之前先脱鞋。 但是您一直在家里穿鞋，所以，这不是问题，对吗？ 问题是您不在自己的房子里，而是在他们的房子里，到目前为止，您已经用错误的脚，鞋，袜子或其他任何东西开始了访问。 仅仅因为您认为自己做的很好，并不意味着您符合房东的标准。 对您而言，“不算是混蛋”的含义可能与他们不同。 如果您的房东只能通过某种方式传达出他们希望您在家里时的表现……

行为守则 (Code of Conduct)

Good news! There’s this thing called a Code of Conduct that a lot of repos have now. They usually have a layout of behavior they expect you to exhibit, as well as negative behavior that they as a project won’t tolerate from you. GitHub even has this nice feature where they provide you a link to one if it exists whenever you make a pull request for the first time on a project. This isn’t a EULA to blindly click through like when you installed iTunes. This is a guide for how you should (and should not) act when participating in this project. The maintainer or maintainers took the time to specify the behavior they expect, so take the time to read it and follow it.

好消息！ 现在，有很多回购协议都具有这种称为“行为准则”的东西。 他们通常具有他们希望您表现出的行为的布局，以及他们作为项目无法容忍的负面行为。 GitHub甚至具有这个不错的功能，当您在项目上首次提出拉取请求时，它们会为您提供一个链接(如果存在)。 这不是像安装iTunes时那样盲目单击的EULA。 这是您参与该项目时应如何(不应该)采取行动的指南。 一个或多个维护者花时间指定他们期望的行为，因此花时间阅读并遵循它。

For example, the Octokit organization has Code of Conduct markdown files in each of their repos.

例如， Octokit组织在每个存储库中都有行为准则标记文件。

“But this has nothing to do with writing code!”

“但这与编写代码无关！”

In my experience, writing software (in both a job setting and an open-source setting) involves equal parts, if not more, the ability to treat others with empathy and respect as it does writing the actual software.

以我的经验，编写软件(包括工作设置和开放源代码设置)涉及相等的部分，甚至更多，这与编写实际软件时一样具有同理心和尊重的能力。

我该如何开始？ (How do I even get started?)

This is probably the hardest part. How do I know what needs working on? A lot of repos use the standard Good First Issue and Help Wanted, which are used to annotate issues that are a good starting point for new contributors. These are great starting points because the maintainer has kept these around to introduce new people to contributing to the project. In larger projects, these can be picked up pretty quickly by other people, so sometimes they can be a little hard to find unassigned. Don’t worry, though — just because an issue doesn’t have one of these labels means that you can’t work on it, it just might require a little more of your time.

这可能是最难的部分。 我怎么知道需要做什么？ 许多回购协议使用标准的Good First Issue和Help Wanted ，它们用于注释问题，这些问题对于新贡献者而言是一个很好的起点。 这些是很好的起点，因为维护人员一直将这些保持在周围，以介绍新的人为该项目做出贡献。 在较大的项目中，其他人可以很快将其提取，因此有时很难找到未分配的项目。 不过，请不要担心-仅仅因为一个问题没有这些标签之一就意味着您无法进行处理，这可能需要花费更多时间。

Commenting on the issue with your intent to work on it is also a good start. Someone may already be working on it, or the issue might not even be valid anymore, so it’s good to check in with the maintainer before you spend time on a change.

打算就此问题发表评论也是一个好的开始。 可能有人已经在进行此工作，或者该问题甚至可能不再有效，因此在花时间进行更改之前最好与维护人员联系。

文档！ (Documentation!)

As a new potential contributor, you are totally the right person to find places in the documentation that don’t quite make sense, or that could have better examples, or that could be more consistent.

作为新的潜在撰稿人，您是完全合适的人，可以在文档中找到不太合理的地方，或者可以找到更好的示例，或者可以更加一致。

It can be easy for someone who knows all of the ins and outs of the project to have trouble explaining it to someone new. This is an example of the Curse of Knowledge, which basically means that once you know a lot about a certain subject, you can lose the ability to teach it to someone else. In terms of effort, there’s less upfront time investment than having to set up an entire environment for that codebase when updating documentation. A great way to improve documentation is to find a project that you actually use at work and think of a time you had to spend time figuring out why some aspect of it wasn’t working the way you expected it to work. Couldn’t figure out all of the options a function takes from the documentation or the project’s GitHub README? Had to go searching for why some feature wasn’t quite working the way you thought it would? If you had trouble, chances are other people spent time trying to figure that out as well. Adding extra clarification to a documentation site or a README can mean the difference between a module working as you expect it to and an hour-long (or more) trek through search results and help forums and source code.

知道项目所有细节的人可能很难向新人解释。 这是“知识诅咒”的一个示例，它基本上意味着，一旦您对某个特定主题了解很多，就可能失去将其教给他人的能力。 就工作量而言，与在更新文档时必须为该代码库设置整个环境相比，前期投资少。 改善文档的一种好方法是找到一个您在工作中实际使用的项目，并考虑一下您必须花些时间来弄清楚为什么该项目的某些方面没有按您预期的方式工作。 无法找出功能从文档或项目的GitHub README中获取的所有选项吗？ 不得不去寻找为什么某些功能不能按照您认为的那样正常工作吗？ 如果您遇到麻烦，其他人也可能会花时间尝试解决这个问题。 在文档站点或自述文件中添加额外的说明可能意味着模块按预期工作与一个小时(或更长时间)的搜索结果，帮助论坛和源代码跋涉之间的区别。

其他注意事项(样式，棉绒，测试，CI / CD) (Other considerations (style, linting, tests, CI/CD))

When making a code change, try to keep it relevant to the issue you’re fixing. If the project uses semicolons, but you have personally vowed to never use them again in your own projects, don’t remove them from every file you touch. Ideally, the project has a formatter like Prettier set up to run on pre-commit or in CI. If not, don’t go rearranging someone’s project just because you happen to like things that way. You’ll likely be asked to revert those changes because the changes will be inconsistent with the rest of the codebase.

进行代码更改时，请尝试使其与要解决的问题相关。 如果项目使用分号，但您个人已发誓不再在自己的项目中再次使用分号，请不要从触摸的每个文件中删除它们。 理想情况下，该项目应将像Prettier这样的格式化程序设置为在pre-commit或CI中运行。 如果没有，请不要仅仅因为您碰巧喜欢某事就去重新安排某人的项目。 您可能会被要求还原这些更改，因为这些更改将与其余代码库不一致。

If the changes you make break existing unit tests, make sure to fix them. The test suite is there to help automate testing each change for any regressions, so it’s imperative that you keep it running. If you fix a bug and no there were no tests to catch that bug, you can go above and beyond and add some test cases for that fix to make sure it doesn’t break again!

如果您所做的更改破坏了现有的单元测试，请确保对其进行修复。 该测试套件可帮助自动测试每个回归的每个更改，因此必须保持其运行。 如果您修复了一个错误，但没有任何测试可捕获该错误，则可以超越此范围，并为该修复添加一些测试用例，以确保它不会再次中断！

Make sure to pay attention to the automated checks that run on your pull request. A lot of repos have some continuous integration pipeline through TravisCI, or GitHub Actions, or whatever, which automatically runs your changes through a pass of lint checking, formatting, and unit tests (and sometimes even functional tests!). The time of the person maintaining the repo is just as valuable as yours, so those checks act as a baseline for them to spend time reviewing and giving you feedback. Ignoring those is a pretty surefire way to not get a response to your changes — or at the very least, a delayed one.

确保注意对您的拉取请求进行的自动检查。 许多存储库通过TravisCI或GitHub Actions或其他任何东西都有一些连续的集成管道，这些管道可以通过lint检查，格式化和单元测试(有时甚至是功能测试！)来自动运行您的更改。 维护存储库的时间与您的宝贵时间一样，因此这些检查是他们花费时间检查并提供反馈的基准。 忽略这些是一种肯定的方法，它不会对您的更改做出响应-至少是延迟的更改。

评价 (The review)

After you’ve opened a pull request and made sure you don’t have any outstanding linting, formatting, or test failures, you’ll hopefully get a review from either the maintainer or some other contributors. It’s important to explain what your change does and why the change is being made. If your change is visual, it definitely helps to provide some screenshots showing the before and after versions of the software with your fix.

在打开拉取请求并确保您没有任何未完成的棉绒，格式化或测试失败之后，希望您能从维护者或其他贡献者那里得到审查。 重要的是要解释您所做的更改以及进行更改的原因 。 如果您所做的更改是直观的，那么一定可以提供一些屏幕快照，其中显示了带有修复程序的软件的之前和之后的版本。

Make sure to follow the Code of Conduct when responding to reviews and criticisms. It’s more than likely the maintainer will ask you to make changes to the pull request you originally provide. Don’t beat yourself up over not being perfect; as a new contributor, you most likely don’t have the context and historical knowledge that a maintainer would have after working with this project for a prolonged amount of time.

回应评论和批评时，请务必遵守《行为准则》。 维护者很可能会要求您更改最初提供的拉取请求。 不要因为不完美而殴打自己； 作为新的贡献者，您很可能没有维护者在长时间处理此项目后所拥有的背景和历史知识。

From here there’s kind of two ways things can go. I’ll highlight the happy path first.

从这里开始，事情可以有两种方式。 我将首先强调幸福的道路。

After some back and forth comments and code changes, your pull request is merged and you’re a contributor now! Yay!

经过一些前后的注释和代码更改后，您的拉取请求将合并，您现在就成为了贡献者！ 好极了！

Another path is that you make a pull request and don’t hear anything for a few days. That’s okay — maintainers are real people with jobs and families and hobbies and lives. Just like how you are volunteering to make some changes or fix some bugs, maintainers are volunteering to maintain the project! If you don’t hear back in a week, post a follow-up comment in the pull request. Hopefully, they’ll see it and you can get some comments and your changes merged. If they don’t respond, they might not have the bandwidth to review and merge your changes right now. DON’T spam them on Twitter asking for a code review; DON’T email them. You don’t know their life, you don’t know what they’re going through personally at the moment. At the end of the day, it’s just software — and software you’re volunteering for, at that.

另一条路径是您发出请求请求，但几天没听到任何声音。 没关系-维护者是真正的人，有工作，有家庭，有嗜好和生活。 就像您自愿更改或修复某些bug一样，维护人员也自愿维护项目！ 如果一周没有收到回音，请在拉取请求中发布后续评论。 希望他们会看到它，并且您可以得到一些评论并将您的更改合并。 如果他们没有回应，他们可能没有足够的带宽来立即查看和合并您的更改。 不要在Twitter上向他们发送垃圾邮件，要求进行代码审查； 不要给他们发送电子邮件。 您不了解他们的生活，您不知道他们目前正在经历的事情。 归根结底，这仅仅是软件，而是您志愿服务的软件。

At the same time, if interacting with people who maintain the project leaves you feeling uncomfortable or you don’t feel like you have the time or fortitude to continue working on something at this time, it’s totally fine to walk away. Your mental and emotional health matters, and you are absolutely under no obligation to volunteer/give away work for free if you don’t feel able to or don’t want to. Remember to take care of yourself!

同时，如果与维护项目的人员进行交互使您感到不自在，或者您不觉得自己有时间或毅力继续进行某些工作，那么走开是完全可以的。 您的心理和情感健康至关重要，如果您感到自己不愿意或不愿意，则绝对没有义务免费自愿/放弃工作。 记住要照顾好自己！

我从这里去哪里？ (Where Do I Go From Here?)

I’d really recommend looking for issues labeled Help Wanted or Good First Issue in open source projects that you use in side projects, or in projects at work. You’ll be more likely to get a response from a smaller project that is still somewhat active than trying to make your first PR on the React repo. A good resource for how to contribute and where to contribute to is https://opensourcefriday.com/#participate. Also, if you feel comfortable doing so, ask your employer if you can set aside some time periodically to work on open source.

我真的建议您在副项目或工作项目中使用的开源项目中查找标记为“ 想要帮助”或“第一好问题”的问题 。 与尝试在React回购上进行首次PR相比，您更有可能从一个仍处于活跃状态的较小项目获得响应。 https://opensourcefriday.com/#participate是有关如何贡献以及在何处贡献的好资源。 另外，如果您觉得这样做很舒服，请询问您的雇主是否可以拨出一些时间定期从事开源工作。