这是对一篇关于在开源社区中支持用户文章的跟进，本文列出了一些关于如何请求维护者帮助解决问题的建议。

您不必遵循这些建议。它们是可选的。遵循这些建议会增加项目维护者花时间帮助您的可能性。重要的是要记住，他们免费支持您的意愿也是可选的。

撰写简洁的 Bug 报告对于社区驱动的开源项目的生命和维护至关重要。做好这一点是对社区的一项巨大贡献。

最小化、完整、可验证的示例

我强烈建议遵循 Stack Overflow 关于最小化、完整、可验证示例的指南。这里我将简要概述其要点：

……代码应该是……

• 最小化 – 使用尽可能少的代码，但仍能重现相同问题
• 完整 – 提供重现问题所需的所有部分
• 可验证 – 测试您即将提供的代码，确保它可以重现问题

说清楚，这很困难，而且需要时间。

作为提问者，我发现创建一个 MCVE 对于一个简单的问题通常需要 10-30 分钟。幸运的是，即使我对遇到问题的软件包了解不多，这项工作通常也很简单。创建最小示例的大部分工作是移除特定于我的应用程序的所有代码，作为提问者，我可能是最适合做这件事的人。

在回答问题时，我经常引导人们查看 StackOverflow 的 MCVE 文档。他们有时会回来提供一个更好的、但尚未达到最小化的示例。本文旨在澄清一些常见问题。

作为示例，我将使用 Pandas DataFrame 的问题。

不要发布数据

您不应该发布您正在使用的文件。相反，尝试看看是否只需几行数据就能重现问题，而不是整个文件。

如果需要下载文件、解压等等，维护者在空闲时间实际运行您的示例的可能性就会大大降低。

不建议这样做

我已将我的数据上传到 Dropbox，您可以从这里获取：my-data.csv.gz

import pandas as pd
df = pd.read_csv('my-data.csv.gz')

建议这样做

您应该能够复制粘贴以下代码来获取足够的数据以引起问题

import pandas as pd
'account-start': ['2017-02-03', '2017-03-03', '2017-01-01'],
'client': ['Alice Anders', 'Bob Baker', 'Charlie Chaplin'],
'balance': [-1432.32, 10.43, 30000.00],
'db-id': [1234, 2424, 251],
'proxy-id': [525, 1525, 2542],
'rank': [52, 525, 32],
...
})

实际上，根本不要包含您的数据

实际上，您的数据可能包含许多特定于您的应用程序的信息。您可能一眼扫过，但维护者不知道哪些是相关的，哪些不是，所以如果您包含这些数据，他们需要花费时间来理解。相反，看看是否可以使用人工或随机数据重现相同的故障。

不建议这样做

这是我足以重现问题的数据

import pandas as pd
'account-start': ['2017-02-03', '2017-03-03', '2017-01-01'],
'client': ['Alice Anders', 'Bob Baker', 'Charlie Chaplin'],
'balance': [-1432.32, 10.43, 30000.00],
'db-id': [1234, 2424, 251],
'proxy-id': [525, 1525, 2542],
'rank': [52, 525, 32],
...
})

建议这样做

我的实际问题是关于在特定时间段内找到排名最高的员工，但我们可以用这个更简单的数据集重现问题。请注意，此数据中的日期是乱序的（2000-01-02 在 2000-01-03 之后）。我发现这对于重现错误至关重要。

import pandas as pd
'account-start': ['2000-01-01', '2000-01-03', '2000-01-02'],
'db-id': [1, 2, 3],
'name': ['Alice', 'Bob', 'Charlie'})

在缩小示例问题的过程中，我们经常会发现很多关于问题原因的信息。这种发现非常有价值，而且只有提问者才能高效地完成。

看看你能把事情做得多小

为了让事情更容易，看看你能把数据做得多小。例如，如果处理表格数据（如 Pandas），那么实际需要多少列才能重现故障？实际需要多少行才能重现故障？列名需要像现在这样命名，还是可以使用“A”和“B”，或者描述其内部类型？

建议这样做

import pandas as pd
'datetime': ['2000-01-03', '2000-01-02'],
'id': [1, 2]})

移除不必要的步骤

您的示例中的每一行都绝对必要才能重现错误吗？如果您可以删除一行代码，请这样做。因为您已经理解您的问题，所以您在做这件事上比维护者效率高得多。他们可能更了解工具，但您更了解您的代码。

不建议这样做

下面的 groupby 步骤抛出了一个我不理解的警告

df = pd.DataFrame(...)

df = df[df.value > 0]
df = df.fillna(0)

df.groupby(df.x).y.mean() # <-- 这产生了错误

建议这样做

下面的 groupby 步骤抛出了一个我不理解的警告

df = pd.DataFrame(...)

df.groupby(df.x).y.mean() # <-- 这产生了错误

使用语法高亮

在使用 Github 时，您可以使用三个反引号（美国标准 QWERTY 键盘左上角的字符）将代码块括起来。它看起来像这样

```python
x = 1
```

提供完整的堆栈跟踪信息

您知道代码和异常之间那些难以理解的内容吗？您应该包含它。

不建议这样做

从以下代码中我得到了一个 ZeroDivisionError

```python
def div(x, y)
return x / y

div(1, 0)
```

建议这样做

从以下代码中我得到了一个 ZeroDivisionError

```python
def div(x, y)
return x / y

div(1, 0)
```

```python-traceback
ZeroDivisionError Traceback (most recent call last)
<ipython-input-4-7b96263abbfa> in <module>()
----> 1 div(1, 0)

<ipython-input-3-7685f97b4ce5> in div(x, y)
1 def div(x, y)
----> 2 return x / y
3

ZeroDivisionError: division by zero
```

如果堆栈跟踪信息很长，没关系。如果您真的想保持整洁，可以将其放在 <details> 标签中。

从以下代码中我得到了一个 ZeroDivisionError

```python
def div(x, y)
return x / y

div(1, 0)
```

### 堆栈跟踪信息

<details>

```python
ZeroDivisionError Traceback (most recent call last)
<ipython-input-4-7b96263abbfa> in <module>()
----> 1 div(1, 0)

<ipython-input-3-7685f97b4ce5> in div(x, y)
1 def div(x, y)
----> 2 return x / y
3

ZeroDivisionError: division by zero
```

</details>

在公开场所提问

在提出问题时，您通常有几个可能的地点

1. GitHub 问题跟踪器
2. Stack Overflow
3. 项目邮件列表
4. 项目聊天室
5. 直接给维护者发邮件（永远不要这样做）

不同的项目对此有不同的处理方式，但他们通常在其文档中有一个页面，说明在哪里寻求帮助。这通常标记为“社区”、“支持”或“在哪里寻求帮助”。以下是 Pandas 社区的建议。

通常，最好在许多维护者都能看到并帮助您的提问的地方提问，这样其他用户将来遇到类似 Bug 时也能找到您的问题和答案。

虽然您的目标可能是解决您自己的问题，但维护者的目标很可能是创建一个记录，说明如何解决类似您这样的问题。这有助于将来遇到类似问题的更多用户看到您精心编写的 Bug 报告，并从随后的对话中学习。

我的个人偏好

• 对于像“做 X 的正确方法是什么？”这样的用户问题，我更喜欢 Stack Overflow。
• 对于像“我做了 X，我非常确信它应该能工作，但我却收到了这个错误”这样的 Bug 报告，我更喜欢 Github issues。
• 对于一般性的闲聊，我更喜欢 Gitter，尽管实际上我个人几乎不在 Gitter 上花时间，因为它未来用户难以搜索。如果您在 Gitter 上问我问题，我几乎肯定不会回复，除非是将您引导到 github、stack overflow 或这篇博客文章。
• 我只喜欢个人邮件，如果有人提议资助或以某种方式认真支持项目的话。

但同样，不同的项目有不同的处理方式和策略。您应该查阅您所处理项目的文档，了解他们喜欢如何支持用户。