如何在 GitHub 上提无聊的小问题

[xiaoxiangmoe]

如何在 GitHub 上提无聊的小问题

VSCode 的一个小 Feature / Bug

今天我向 jiyun 同学安利了一发 tsdoc，以及在 TypeScript 中如何用 tsdoc 标注让我们使用 API 时候更开心。

这时候，我们发现了在 TSDoc 中，我们如果使用 TSDoc Playground 中的 code samples 功能的话，每次都会在 code sample 结尾多一行空行，然后我建议 jiyun 去 GitHub 向 VSCode 开发者问一下，这是一个 Bug 还是一个 Feature。

提问过程

首先，我们发现 Bug report / Feature request / Question 三个选项，然后开发者告诉我们不要提 Question，要去 stackoverflow 提。这种情况嘛，既然是想提无聊的小问题，那就当 bug 提呗，我们去点 Bug report

然后，jiyun 写下了他的基本配置：

VSCode Version: 1.29.1
OS Version: macOS Mojave 10.14.1

这告诉了我们，一般提问题，我们是要告诉开发者准确的环境，版本，方便他们定位问题。

然后我们要写 Steps to Reproduce，这，，，

刚刚好，我在写 React，发现了 React 的 Hooks API 的 dts 文档，刚刚好有用 code samples，我建议 jiyun 选择用它作为 Reproduce demo，毕竟这是广为人知的东西，并且已经被发布了。

好,写下：

Steps to Reproduce:
1.npm install react@next @types/react
2. create a .tsx file and write

import * as React from 'react';
React.useMemo

然后配上一副图

完毕。

修改 1

这里有这种问题，我们的图中并没有突出问题，比如结尾的*太不明显了。
我们应该滚一下注释，把 空行的 * 放到居中的位置，并且 P 个图，加上红色箭头把问题的重点指出来。

见图：

修改2

我们给了复现的例子，但是作者很忙不愿意去复现怎么办呢？我们把关键代码截出来好了，这是一个 tsdoc 的注释代码，我们打开 node_modules 里的源码去复制粘贴就好

   /**
     * `useMemo` will only recompute the memoized value when one of the `inputs` has changed.
     *
     * Usage note: if calling `useMemo` with a referentially stable function, also give it as the input in
     * the second argument.
     *
     * ```ts
     * function expensive () { ... }
     *
     * function Component () {
     *   const expensiveResult = useMemo(expensive, [expensive])
     *   return ...
     * }
     * ```
     *
     * @version experimental
     * @see https://reactjs.org/docs/hooks-reference.html#usememo
     */
    function useMemo<T>(factory: () => T, inputs: InputIdentityList): T;

完毕。

修改3

我们从 node_modules 里面复制粘贴代码，肯定别人不清楚，所以我们应该给出线上仓库的源码。

找到了，附上去：

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react/index.d.ts

这还不够，我们需要加上行数，方便查看，点击左边的行号，我们得到

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react/index.d.ts#L891

最好是行号的范围吧，我也不知道怎么点击得到，但是看别人的例子，我记得加上 -L910 就可以得到范围，所以我们得到了

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react/index.d.ts#L891-L910

修改4

我们这个问题当下貌似没啥大问题了，但是随着时间的推移呢？这肯定会出问题，因为 URL 中用的是 blob/master,而且我们在 Steps to Reproduce 用的是 react@next @types/react,都依赖的是变化的东西。我们应该在提问题时候给出确定的东西，让别人在几年后，十几年后依旧可以在一定程度上复现。

所以我们应该改成

npm install [email protected] @types/[email protected]

以及点击

获得代码提交特定的版本，然后把 url 换成提交的 commit 的 SHA-1 定位的 url

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/9414e3cb3a771a2f6b6b32b9290c70dee343ec23/types/react/index.d.ts#L891-L910

最后，我们终于提了一个很无聊的小问题。

---

总结：

• 提问时候要带上自己的环境
• 提问时候要给可复现的步骤（VSCode 的问题给可复现步骤就够了。但是前端组件库的问题，建议给在线的可复现的 demo，比如 codesandbox / jsbin 等地方，写上能复现问题的代码，保留个链接，附到问题中，让作者打开链接就能看到你的问题，并且做修改。如果是 Java/Node/Go 等写的后台项目，你应该把业务代码刨除，然后留下一个最小可复现的 demo，并且弄好编译脚本，开启一个 repo，把代码放上去，让其他同学 clone 下来可以直接跑你的代码）
• 有必要的情况下，给出关键的图，并且给图上的重要地方 P 上箭头，下划线等标记
• 给出某些你认为重要的源码的行号，链接
• 所有东西要注意考虑时效性，别给那种过一些时间就不能复现的东西。比如 npm release 的 tag，要注意这是长期 tag 或者可变 tag。

[bolasblack]

想要获得某个文件在当前 commit 的 url ，你可以在 GitHub 网页打开了这个文件的时候按下 y 键，url 会自动变成带了 commit hash 的版本