贡献者指南

开发一个开源项目，尤其是一个有活力、生命力和影响力的开源项目是一件相当困难的事情，对于cnmaps的开发，我深知一个人能力有限，所以非常欢迎各位Python和GIS爱好者能和我一起来参与这个开源项目的继续开发。

哪些人适合参与到cnmaps的开发中？

在回答这个问题之前，我们先来明确一个概念：什么人可以被称为“开源贡献者”？

在我看来，并不是只有撸代码、实现功能的人才算得上“开源贡献者”，那些为开源项目做测试、提交bug报告、补充文档以及提出新功能需求和参与讨论的人，都算是“开源贡献者”。或者换句话说，所有努力让开源项目变得更好的人，都是“开源贡献者”。

现在我们来回答哪些人适合参与到cnmaps的开发中的问题，我的答案是：

对开源项目有热情且愿意付出时间与人合作一起让开源项目变得更好的人。
会使用或愿意学习使用GitHub的Issue功能的人。
会使用或愿意学习使用Git、Python的人。
有能力且有意愿补充和完善文档的人。
对代码质量有追求的人（有代码洁癖的人）。
对开源项目的功能有自己想法并且愿意分享想法的人。
…

如何参与到cnmaps的项目中来？

我大致将参与cnmaps项目的形式分为 文档编写 、测试、讨论、开发这四个部分。

文档编写

cnmaps的文档（也就是当前你正在阅读的这个文档）是使用Python语言的sphinx框架托管于GitHub并与Readthedocs.org集成实现的，若你想要完善文档，则可以fork本文档的代码仓库： cnmaps-doc ，在你本地进行修改和测试后向主仓库提交Pull Request，在我（们）审核之后会自动合并到主分支并进行构建发布。

测试

以使用者的角度测试项目的各项功能，在发现bug以后，去 Issues页面提交议题（Issue），最好能针对发现的bug写出测试用例。你也可以在项目的tests目录中补充测试用例，这可能需要你能熟练使用pytest测试框架。

讨论

如果你对代码并不熟悉，或者对代码质量不自信，但是对项目的功能有自己的想法，也可以通过在 Issues页面中提出自己的功能需求的方式参与项目（类似于产品经理提出需求），当然也并不限于需求的讨论，对于GIS知识等非代码的一些认知偏差纠正或者指出、修复地图的拓扑错误也算，当然如果你能提供好的数据源也是非常重要的，比如你可以提供一套质量很高的地理边界。

开发

如果是想参与到cnmaps的代码的开发，相对来说限制会多一些。首先你必须对代码质量有追求，在平时撸代码的时候会尽量以优雅地方式实现代码，具体来说可能要满足以下几条：

了解PEP8和Google的Python代码规范，并愿意遵守其大部分原则。
在平时的开发中会使用pylint等工具对自己的代码进行自动化审查。
能够接受“测试驱动开发”（TDD）的工作方式，认同“质量优于速度”的理念。
会写测试用例，会进行单元测试。
乐于交流，愿意用最直接高效的方式交流，不要求所谓的空杯心态，但也不要过于傲慢。

目前cnmaps接受开发贡献的方式是fork + PR（Pull Request）+ 审查合并，但是在提交PR之前需要先有Issue议题来描述修改的动机和拟实现的功能及测试用例，所以正确的顺序是打开议题 -> fork分支 -> 本地开发测试 -> 提交PR -> 审查合并 -> 关闭议题。