# 钻石铲贡献指南

嘛, 在这之前我得先道谢一下, 感谢您愿意花时间来帮助我, 您的贡献将会使钻石铲变得更好!

但也请在作出行动前, 阅读我们的[行为守则](CODE_OF_CONDUCT.md), 以确保您的行为是我们能够接受的, 以避免不必要的误会和麻烦

## 如何贡献

### 不需要写代码也能做的事情

- 通过[提出问题](https://github.com/diamond-shovel/diamond-shovel/issues/new)来报告问题
  - 如果您发现了一个Bug, 请提供钻石铲究竟做了什么, 并且应该做什么的详细描述, 以及如何重现这个问题
  - 如果您有一个新的功能想法, 大胆的说出您的想法, 说出您想看到的东西, 如果能提供一些效果或者原型那就更好了
  - 在提出问题前, 最好还是能搜索一下是不是已经有先人已经问过了, 如果有, 可以在那下面继续讨论

- 代我们帮助那些遇到问题的用户, 在issues区冲浪时您可能能够找到一些您能帮忙解决的问题, 请不要犹豫, 请尽管帮助他们. 或者您也可以帮我们在这个问题下找到更多的细节, 以便我们更好地解决问题
- 帮我们测试一下来自其他人的[Pull Request](https://github.com/diamond-shovel/diamond-shovel/pulls), 看看它们是否真的解决了问题, 以及是否需要进一步的改进. 通过这些小事您能够帮助钻石铲变得更加稳定和可靠!
- 发现了安全问题? 低调, 先低调, 在汇报问题之前请先看看我们的[安全政策](SECURITY.md), 您会在那里看到详细的汇报流程


### 想给钻石铲补充代码的话

接下来的事情很重要! 这会让您的贡献得到更好的接纳

#### 一些补充
* `Dockerfile`与`.gitlab-ci.yml`为我们*内部*所使用的文件, 请通过`python -m build`来手动打包钻石铲, 我们对这些文件的兼容性问题不作任何保证!

#### Pull Requests

* **最好**在对代码进行修改前, 切出一个专用的分支, 而不是直接在`master`上修改. 我们希望您的分支命名能够接受<cite>[分支约定][1]</cite>
* **最好**在您的提交消息中遵守<cite>[约定式提交][2]</cite>
* **最好**在您的代码中包含一些测试, 以确保您的代码是可靠的, 并且不会在未来的版本中被破坏
* 如果您想确保没有其他人在您已经正在解决的问题上浪费时间, 可以考虑提交一个<cite>[草稿Pull Request][3]</cite>
  * 同时**请**在Pull Requests的标题上标注`[WIP]`以表示这是一个草稿
* **请**在确保标题包含了您想要处理的工作, 以便我们能尽快搜索到您的Pull Request
* 如果您的Pull Request是为了解决一个问题, **请**在Pull Request的描述中包含`Fixes #<issue number>`以便于我们自动关闭这个问题
* 请**不要**在Pull Requests的描述中留空, 请尽可能详细地描述您的工作, 以便于我们更好地理解您的工作
* 请**不要**抛弃您的Pull Request, 毕竟这是您在钻石铲上的劳动成果
* 请**不要**在您的Pull Request中包含不必要的文件, 我们的硬盘空间有限, 也不要压榨您的硬盘空间, 尽可能把它们放在`.gitignore`中
* 请**不要**在古代Pull Request中提出新的问题

#### 代码风格

众所周知, Python是一个对游标卡尺要求很高的语言, 请确保您的代码符合我们的代码风格, 以便于我们能够更方便的理解并帮助维护您的代码

* **最好**将独立的功能单独分出一个函数/方法, 能够十分有效地在避免不必要注释和重复代码的情况下提高代码的可读性
* **最好**在函数/方法的开头写上一个简短的文档
* 注释**最好**是说明*为什么*而不是*如何*, 这一条请与第一条结合使用
* **最好**保持和我们一致的命名风格
  * **最好**使用`snake_case`来命名变量和函数
  * **最好**使用`CamelCase`来命名类
  * **最好**使用`UPPER_CASE`来命名常量
* 我们所使用的Tab长度是4个空格, **请**使用空格来缩进, 以避免不必要的`IdentionError`导致的额外工作
* **最好**在您的代码中包含一些类型提示, 以便于后续我们更好的使用和维护您的代码

#### 涉及到新功能

钻石铲最终是一个框架, 它并不十分具体地涉及到某一个领域.
因此请确保您的功能是通用的, 并且能够被其他人所使用, 以便于我们能够更好地接纳您的工作

而相对具体的功能, 请考虑将其作为一个插件来实现:3

#### 涉及到Bug修复

* **请**在您的改动中做好最完备的测试, 因为在框架/轮子中, 一个小小的改动也可能导致整个系统的行为发生变化
* 一个Pull Request中**尽可能**只包含一个Bug修复, 这能够方便我们更好的追踪我们的工作进度和您的贡献
* **请**包含修复的复现步骤, 这能够帮助我们更快的测试您的工作是否有效
* **请**在Pull Request的描述中包含`Fixes #<issue number>`以便于我们自动关闭这个问题

### Bug报告

* 条件允许的话, **尽可能**地提供钻石铲所处的运行环境, 部分铲子可能会有"水土不服"的情况, 而这种情况一般在我们的环境下很难复现
* **请**提供钻石铲的版本号, 有些Bug可能已经在新的版本中被摘了
* **请**提供复现步骤, 这能够帮助我们更快地定位问题根源
* **请**提供您原本期望的行为, 以及钻石铲实际做了什么, 做了比较才能更快地诊断问题
* **不要**在已经关闭的Pull Request/Issue下提出新的问题, 这会使我们无法追踪您的问题
* **不要**将商业版的问题提到这里, 因为这会有很大概率泄漏您的商业信息, 请通过[商业支持](https://diamond-shovel.com)来解决这个问题
* **请**在汇报一个新的问题前, 请先搜索一下是不是已经有人提出过了, 如果有, 请在那个问题下继续讨论, 如果允许, 可以帮助补充一些细节

最终, 我们感谢您对钻石铲的贡献, 感谢您的时间和精力, 感谢您的耐心和理解, 感谢您的支持和帮助

[1]: https://gist.github.com/jpolete/aa31b9043e8e90f8a47c7738669555fa
[2]: https://www.conventionalcommits.org/en/v1.0.0/
[3]: https://github.blog/2019-02-14-introducing-draft-pull-requests/
