github组织存储库使用

by Sam Westreich, PhD

由Sam Westreich博士

为什么我不使用您的GitHub存储库 (Why I’m not using your GitHub repository)

As a bioinformatician, I reside in an interesting middle ground between developers and end users. My background training is in biology, not computer science.

作为生物信息学家，我住在开发人员和最终用户之间一个有趣的中间地带。 我的背景训练是生物学，而不是计算机科学。

But in recent years, biology has moved closer to computer science. Many types of biological data are too big to analyze by hand and must be processed using computers. The ever-decreasing cost of genome sequencing has introduced vast amounts of sequence data. All this data needs to be assembled, compared, searched, and annotated.

但是近年来，生物学已逐渐接近计算机科学。 许多类型的生物数据太大，无法手工分析，必须使用计算机进行处理。 基因组测序成本的不断下降已经引入了大量的序列数据。 所有这些数据都需要组装，比较，搜索和注释。

More and more, biologists need computers.

生物学家越来越需要计算机。

More specifically, biologists need computer programs. Look, if I’ve got a bunch of sequence data from a microbiome that I want to match up to the different species of origin, I’m not going to sit down and build my own aligner tool from scratch. I’m going to grab an off-the-digital-shelf tool that’s been used before, pray that it is fairly straightforward to install, and plug it in.

更具体地说，生物学家需要计算机程序。 看，如果我想从微生物组中获得一堆序列数据，希望与不同的起源物种相匹配，那么我就不会坐下来从头开始构建自己的比对工具。 我将抢先使用一个现成的数字化工具，祈祷它安装起来非常简单，然后将其插入。

In graduate school, I made a mistake. I allowed the fast pace of the computer world to seduce me. “No more multi-week experiments at the lab bench!” I declared to myself. “I’m going to dive headlong into the computer side of biology and become a bridge between both worlds — a bioinformatician!”

在研究生院，我犯了一个错误。 我允许计算机世界的快速发展引诱我。 “不再需要在实验室工作台进行多周的实验！” 我对自己宣布。 “我将全力投入生物学的计算机领域，并成为两个世界之间的桥梁- 生物信息学家 ！”

In theory, a bioinformatician analyzes data gathered by biologists, discovering new conclusions and forging new connections.

从理论上讲，生物信息学家会分析生物学家收集的数据，以发现新的结论并建立新的联系。

In practice, a bioinformatician installs a lot of programs and curses the developers who created them.

在实践中，生物信息学家会安装许多程序并诅咒创建它们的开发人员。

I’ve given up on many programs — some of which, I assume, are very good programs — because of nonsensical instructions, bad code, or horrible documentation.

由于无意义的指令，错误的代码或糟糕的文档，我已经放弃了许多程序(我认为其中有些是非常好的程序)。

It’s gotten to the point where I can glance at a GitHub repository and get a good sense of how I’ll feel about your tool.

至此，我可以浏览GitHub存储库并很好地了解我对您的工具的看法。

Some repos instil confidence. Others fill me with dread.

一些回购注入信心。 其他人让我感到恐惧。

Sometimes, I find one so bad that I refuse to even attempt to install the tool (unless it’s demanded by my boss).

有时，我发现一个问题很糟糕，以至于我什至拒绝尝试安装该工具(除非老板要求)。

Here are the biggest issues I see, and how to avoid them.

这是我看到的最大问题，以及如何避免它们。

原因1：没有文档 (Reason 1: No documentation)

I’ve seen every variation of documentation:

我看过各种文档资料：

• Documentation written in the Readme.
  自述文件中编写的文档。
• A “quick how-to” in the Readme, with detailed information in a separate PDF or Word document.
  自述文件中的“快速操作方法”，以及单独的PDF或Word文档中的详细信息。
• A link to a GitHub wiki.
  GitHub Wiki的链接。
• A link to an external site, with documentation written there.
  指向外部站点的链接，并在其中写有文档。
• A link to an external site, where there’s another link to download a PDF. (Why not just put the PDF in the repo?)
  指向外部站点的链接，这里有另一个下载PDF的链接。 (为什么不将PDF放入回购中？)

• Worst of all… no documentation.

  最糟糕的是…… 没有文档。

Yes, I know that writing documentation is awful. I’ve built pipelines and tools, and I’ve forced myself to write documentation. I’ve forgotten about edge cases and the particulars of commands, and have sometimes received embarrassing reminders from users.

是的，我知道编写文档非常糟糕。 我建立了管道和工具，并强迫自己编写文档。 我忘记了极端情况和命令的特殊性，有时会收到用户的尴尬提醒。

If you build a tool and make it public, your documentation should include, at minimum:

如果要构建工具并将其公开，则文档至少应包括：

1. The requirements and dependencies to use your tool. This includes both hardware requirements (RAM and disk size) and software requirements (operating system, other programs).
   使用您的工具的要求和依赖性。 这包括硬件要求(RAM和磁盘大小)和软件要求(操作系统，其他程序)。
2. How to install your tool.
   如何安装工具。
3. What your tool does.
   您的工具做什么。
4. How to make your tool do those things, with example commands.
   如何使用示例命令使工具完成这些任务。

I also highly recommend that you include:

我也强烈建议您包括：

1. A ‘frequently asked questions’ section.
   “常见问题”部分。
2. Tests — this includes test data and the exact commands that should be used on that test data (to the level where the commands should be copy/pasted onto the command line).
   测试-这包括测试数据和应在该测试数据上使用的确切命令(达到将命令复制/粘贴到命令行的级别)。
3. Examples of output.
   输出示例。
4. A license.
   许可证。
5. Screenshots, if applicable.
   屏幕截图(如果适用)。
6. Acknowledgements, whether you’re open to pull requests, and contact information, so users can report issues.
   致谢，无论您是否愿意提出请求和联系信息，以便用户可以报告问题。

Bad or incomplete documentation is the number one reason I stop using a tool. You know how your tool works, but no one else does — don’t force people to figure it out. Give clear and easy instructions.

错误或不完整的文档是我停止使用工具的第一原因。 您知道您的工具是如何工作的，但是没有人能做到-不要强迫人们弄清楚它。 给出清晰，简单的说明。

原因2：依赖地狱 (Reason 2: Dependency hell)

I once found a tool (a pipeline for DNA sequence annotation) that had six dependencies.

我曾经发现一个具有六个依赖项的工具(DNA序列注释的管道)。

“That’s not the worst,” I thought to myself. “I can handle installing six dependencies to use this tool.”

“那不是最坏的情况，”我心想。 “我可以安装六个依赖项来使用此工具。”

Unfortunately, most of those dependencies had other dependencies. And those had even more dependencies, including some that refused to play nicely with each other.

不幸的是，大多数依赖项还具有其他依赖项。 那些人甚至有更多的依赖关系，包括一些拒绝彼此友好相处的人。

By the time I gave up on that original tool, I’d come across nineteen different dependencies that I’d need to install, specifically to use this single pipeline. Nineteen!

到我放弃该原始工具的时候，我遇到了需要安装的十九个不同依赖项，特别是要使用此单一管道。 十九岁 ！

It’s great that there are plenty of useful tools out there that can serve as the building blocks for more complex programs. It’s much better to use an already existing, already recognized dependency than it is to reinvent the wheel and do it all yourself.

非常高兴有很多有用的工具可以用作更复杂程序的构建块。 使用现有的，已经公认的依赖关系要比重新发明轮子并自己完成所有工作要好得多。

But if you take this route, please find an easier way for me to install the dependencies for your tool.

但是，如果您采用这种方法，请为我​​找到一种更简便的方法来为您的工具安装依赖项。

Give me an install script that I can run to get all dependencies — this works especially well if I need a half-dozen Python or R packages. If possible, give me an archive of the dependency, so I don’t need to go and hunt it down (assuming that the license for the dependency permits this level of redistribution).

给我一个可以用来获取所有依赖项的安装脚本-如果我需要六个Python或R软件包，则该脚本特别好用。 如果可能的话，请给我一个相关性的档案，所以我不需要去寻找它(假设相关性的许可证允许这种级别的重新分配)。

Don’t trap me in dependency hell — or if you do, be prepared to see many users give up on using your program. No one wants to spend time in hell.

不要让我陷入依赖地狱中-否则，请准备好让许多用户放弃使用您的程序。 没有人愿意在地狱中度过时光。

原因3：遗弃问题 (Reason 3: Abandonment issues)

When a GitHub project is new and fresh, there are no issues. It’s new, it’s clean, and no one’s stumbled across the bugs yet.

当GitHub项目是新的和新鲜的时，就没有问题。 它是新的，很干净，而且还没有人发现错误。

Over the next couple of weeks to months, as users find the program and test it out, they will raise issues. Thankfully, GitHub has a page on each repository dedicated to logging these issues. It’s called “Issues.”

在接下来的几周到几个月中，随着用户找到并测试该程序，他们将提出问题。 值得庆幸的是，GitHub在每个存储库上都有一个页面专门记录这些问题。 它称为“问题”。

Here, on this page, users comment that they get an error message when they try various tasks. Sometimes, it’s an out-of-date dependency. Sometimes, it’s a typo in the code. Sometimes, it’s user error — they have the wrong version of another tool, their inputs are in the wrong format, or they’re using illegal options and not reading the help messages.

用户在此处在此页面上评论说，他们在尝试各种任务时会收到一条错误消息。 有时，这是过时的依赖关系。 有时，这是代码中的错字。 有时，这是用户错误-他们使用的是其他工具的版本错误，输入格式错误或使用了非法选项而不阅读帮助消息。

On the surface, this is a great feature. But this Issues page can also be a warning — or a deterrent.

从表面上看，这是一个很大的功能。 但是，此“问题”页面也可以是警告或威慑作用。

An Issues page can throw up one of two red flags — or a green flag:

问题页面可以抛出两个红色标记之一或一个绿色标记：

• Red flag 1: There are no issues. There have never been any issues. No one has ever used this tool, and it’s abandoned and gathering dust.

  红旗1：没有问题。 从来没有任何问题。 没有人曾经使用过这种工具，并且它已经被丢弃并积尘。

• Red flag 2: There are several open issues, mostly about errors, with no resolution from the repo owner. This tool is abandoned and broken and the owner doesn’t care.

  危险信号2：存在几个未解决的问题，大部分是关于错误的，仓库所有者未解决。 该工具已被废弃和破坏，所有者并不在意。

• Green flag: There are very few open issues, most of which are tagged as enhancements — but lots of closed issues. The owner is actively fixing errors, helping users, and plans to add more features.

  绿旗：很少有未解决的问题，其中大多数被标记为增强功能-但是很多未解决的问题。 所有者正在积极修复错误，为用户提供帮助，并计划添加更多功能。

Because I’ve published programs on GitHub, I know that maintaining them isn’t fun. It’s fun to create something new. It’s not fun to troubleshoot strange error messages and obtuse use cases. It’s not fun to pour back over pages of old code and figure out why a super-specific condition leads to failure.

因为我已经在GitHub上发布了程序，所以我知道维护它们并不有趣。 创造新事物很有趣。 对奇怪的错误消息进行故障排除并钝化用例并不有趣。 倒回旧代码的页面并弄清楚为什么超级特定的条件会导致失败，这并不是一件有趣的事情。

But the best programs (and the most trustworthy GitHub repos) come from creators who are willing to do the boring, dull work. That includes fixing issues and providing support for users.

但是最好的程序(也是最值得信赖的GitHub仓库)来自愿意做无聊而乏味的工作的创建者。 这包括解决问题并为用户提供支持。

And if other questions are being answered, I feel more confident that my own problems will be addressed, and I’ll be able to confidently use the tool for my own purposes.

如果要回答其他问题，我将更有信心解决自己的问题，并且能够自信地将工具用于自己的目的。

卖给我你的程序 (Sell me on your program)

Like it or not, your GitHub repository is often the ‘face’ of your program. Your repo needs to sell your program as easy to install, easy to run, and easy to understand.

不管喜欢与否，您的GitHub存储库通常是程序的“面Kong”。 您的仓库需要以易于安装，易于运行和易于理解的方式出售程序。

A great GitHub repo is a beautiful thing. As a semi-skilled user, I love when a readme file tells me exactly what commands to install the tool, how to use it, and how to troubleshoot the most common issues. A detailed and straightforward manual puts a smile on my face. A one-step dependency install script makes me breathe a sigh of relief. Indications that you’re supporting your tool and fixing bugs causes my chest to fill with confidence.

一个很棒的GitHub回购是一件美丽的事情。 作为一个半熟练的用户，我很喜欢自述文件告诉我确切的命令来安装该工具，如何使用它以及如何解决最常见的问题。 详尽而直接的手册使我满脸笑容。 一步的依赖安装脚本使我松了一口气。 您正在支持工具并修复错误的迹象使我的胸部充满信心。

Let me use your tool.

让我使用您的工具。

Let me cite your work and sing your praises to my colleagues.

让我引用您的工作，并向我的同事们赞扬。

Let me respect you and the great program you’ve built.

让我尊重您和您建立的出色程序。

Avoid these issues — and avoid these errors in your next public-facing GitHub repository.

避免这些问题，并在下一个面向公众的GitHub存储库中避免这些错误。

Sam Westreich is a microbiome scientist working in Silicon Valley, and has spent years immersing himself in science and the nerdiest of pursuits. He blogs about science, biology, microbes and microbiomes, and his thoughts on graduate school and finding success.

萨姆·韦斯特赖奇(Sam Westreich)是一位在硅谷工作的微生物组科学家，他花了多年的时间将自己沉浸在科学和最疯狂的追求中。 他撰写有关科学，生物学，微生物和微生物组学的博客，以及他对研究生院和寻求成功的看法。

翻译自: https://www.freecodecamp.org/news/why-im-not-using-your-github-repository-2dff6c7ac7cf/

github组织存储库使用