如何贡献

我非常欢迎任何有助于改进和扩展 mlxtend 功能的贡献。

快速贡献者清单

这是一个关于典型贡献 mlxtend（以及其他开源项目）不同步骤的快速清单。建议将此列表复制到本地文本文件（或问题跟踪器）中，并在进行过程中逐项勾选。

2. 同步你的 Fork

首先，通过执行以下命令获取原始项目主分支的更新：

$ git fetch upstream

你应该会看到以下输出：

remote: Counting objects: xx, done.
remote: Compressing objects: 100% (xx/xx), done.
remote: Total xx (delta xx), reused xx (delta x)
Unpacking objects: 100% (xx/xx), done.
From https://github.com/rasbt/mlxtend
 * [new branch]      master     -> upstream/master

这意味着 rasbt/mlxtend 主分支的提交现在存储在本地分支 upstream/master 中。

如果你尚未切换到本地项目的主分支，请执行：

$ git checkout master

最后，通过执行以下命令将 upstream/master 中的更改合并到你的本地主分支：

$ git merge upstream/master

这将给你一个类似以下的输出：

Updating xxx...xxx
Fast-forward
SOME FILE1                    |    12 +++++++
SOME FILE2                    |    10 +++++++
2 files changed, 22 insertions(+),

*主要工作流程 - 在新主题分支中进行更改

以下列出了贡献的9个典型步骤。

1. 讨论功能或修改

在开始编码之前，请在项目的问题跟踪器上讨论新功能、错误修复或其他修改。在打开“新问题”之前，请快速搜索以查看是否已有类似的问题提交。

2. 创建新功能分支

请避免直接在主分支上工作，而是创建一个新的功能分支：

$ git branch <new_feature>

通过执行以下命令切换到新功能分支：

$ git checkout <new_feature>

3. 开发新功能/修复错误

现在是时候修改现有代码或为项目贡献新代码了。

4. 测试你的代码

添加相应的单元测试并检查它们是否通过：

$ PYTHONPATH='.' pytest ./mlxtend ---with-coverage

5. 记录更改

请在 mlxtend/docs/sources/changelog.md 文件中添加一个条目。如果是新功能，如果能在 mlxtend/sources 的适当位置更新文档，那就更好了。

6. 提交更改

当你准备好提交更改时，请提供一个有意义的 commit 消息：

$ git add <modifies_files> # 或 `git add .`
$ git commit -m '<meaningful commit message>'

7. 可选：压缩提交

如果你进行了多次较小的提交，最好将它们分组为一个较大的总结性提交。首先，通过以下命令列出你最近的提交：

注意
由于 GitHub UI 的改进，这不再必要/不鼓励。

$ git log

默认情况下，这将按从新到旧的顺序列出提交，格式如下：

commit 046e3af8a9127df8eac879454f029937c8a31c41
Author: rasbt <mail@sebastianraschka.com>
Date:   Tue Nov 24 03:46:37 2015 -0500

    fixed setup.py

commit c3c00f6ba0e8f48bbe1c9081b8ae3817e57ecc5c
Author: rasbt <mail@sebastianraschka.com>
Date:   Tue Nov 24 03:04:39 2015 -0500

        documented feature x

commit d87934fe8726c46f0b166d6290a3bf38915d6e75
Author: rasbt <mail@sebastianraschka.com>
Date:   Tue Nov 24 02:44:45 2015 -0500

        added support for feature x

假设将这3个提交分组到一个提交中是有意义的，我们可以执行：

$ git rebase -i HEAD~3

这将打开默认的 git 编辑器，内容如下：

pick d87934f added support for feature x
pick c3c00f6 documented feature x
pick 046e3af fixed setup.py

由于 c3c00f6 和 046e3af 与 feature x 的原始提交相关，让我们保留 d87934f 并将接下来的两个提交压缩到这个初始提交中，方法是将行更改为：

pick d87934f added support for feature x
squash c3c00f6 documented feature x
squash 046e3af fixed setup.py

现在，在编辑器中保存更改。退出编辑器将应用 rebase 更改，编辑器将再次打开，提示你输入新的提交消息。在这种情况下，我们可以输入 support for feature x 来总结这些贡献。

8. 上传更改

通过执行以下命令将你的更改推送到 git 服务器上的主题分支：

$ git push origin <feature_branch>

9. 提交 `pull request`

转到你的 GitHub 在线仓库，选择新功能分支，并提交一个新的拉取请求：

开发者须知

构建文档

文档通过 MkDocs 构建；为了确保文档正确渲染，你可以通过在 mlxtend/docs 目录中执行 mkdocs serve 来在本地查看文档。

例如：

~/github/mlxtend/docs$ mkdocs serve

1. 构建 API 文档

要构建API文档，请导航到 mlxtend/docs 并在此目录下执行 make_api.py 文件：

~/github/mlxtend/docs$ python make_api.py

这应将API文档放置到以下两个目录中的正确位置：

mlxtend/docs/sources/api_modules
mlxtend/docs/sources/api_subpackes

2. 编辑用户指南

包含“用户指南”代码示例的文档是从IPython Notebook文件生成的。为了在编辑后将IPython笔记本文件转换为Markdown，请按照以下步骤操作：

修改或编辑现有的笔记本。
执行当前笔记本中的所有单元格，并确保没有错误发生。
使用 ipynb2markdown.py 转换器将笔记本转换为Markdown

~/github/mlxtend/docs$ python ipynb2markdown.py --ipynb ./sources/user_guide/subpackage/notebookname.ipynb

注意

如果您正在添加新文档，请同时将其包含在 mlxtend/docs/mkdocs.yml 文件的pages部分中。

3. 构建文档的静态HTML文件

首先，请通过本地主机（https://127.0.0.1:8000/）检查文档：

~/github/mlxtend/docs$ mkdocs serve

接下来，通过以下命令构建mlxtend文档的静态HTML文件：

~/github/mlxtend/docs$ mkdocs build --clean

要部署文档，请执行：

~/github/mlxtend/docs$ mkdocs gh-deploy --clean

4. 生成文档的PDF版本

要生成文档的PDF版本，只需进入 mlxtend/docs 目录并执行：

python md2pdf.py

将新版本上传到PyPI

1. 创建新的测试环境

假设我们使用 conda，通过以下命令创建一个新的Python环境：

$ conda create -n 'mlxtend-testing' python=3 numpy scipy pandas

接下来，通过执行以下命令激活环境：

$ source activate mlxtend-testing

2. 从本地文件安装包

通过执行以下命令测试安装：

$ python setup.py install --record files.txt

--record files.txt 标志将创建一个 files.txt 文件，列出这些文件将被安装的位置。

尝试导入包以查看是否正常工作，例如通过执行：

$ python -c 'import mlxtend; print(mlxtend.__file__)'

如果一切看起来正常，通过以下命令移除安装：

$ cat files.txt | xargs rm -rf ; rm files.txt

接下来，测试 pip 是否能够安装包。首先，导航到一个不同的目录，然后从那里安装包：

$ pip install mlxtend

并再次卸载它：

$ pip uninstall mlxtend

3. 部署包

首先考虑将包部署到PyPI测试服务器。设置说明可以在这里找到：https://wiki.python.org/moin/TestPyPI。

首先，如果您还没有安装Twine，请安装它。例如，使用以下命令安装所有推荐的包：

$ python -m pip install twine build

其次，创建分发包。默认情况下，这会在 ./dist 目录中创建一个sdist和一个wheel。

$ python -m build

安装wheel和sdist以确保它们正常工作。分发文件名会随着每个版本而变化。

python -m pip install ./dist/mlxtend-0.23.0.dev0.tar.gz --force-reinstall
python -m pip install ./dist/mlxtend-0.23.0.dev0-py3-none-any.whl --force-reinstall
python -m pip uninstall mlxtend

第三，将包上传到测试服务器：

$ twine upload --repository-url https://upload.pypi.org/legacy dist/

然后，安装它并查看是否正常工作：

$ pip install -i https://testpypi.python.org/pypi mlxtend

接下来，再次卸载它：

$ pip uninstall mlxtend

第四，在这次干运行成功后，使用“真实”的PyPI重复此过程：

$ python -m twine upload  dist/*

4. 移除虚拟环境

最后，为了清理本地驱动器，通过以下命令移除虚拟测试环境：

$ conda remove --name 'mlxtend-testing' --all

注意：

如果您遇到类似以下的错误：

HTTPError: 403 Forbidden from https://upload.pypi.org/legacy/

请确保您安装了最新版本的Twine（对我来说，卸载conda中的版本并通过pip安装有所帮助。）

5. 更新conda-forge配方

一旦mlxtend的新版本上传到PyPI，请在 https://github.com/conda-forge/mlxtend-feedstock 更新conda-forge构建配方，通过适当更改 recipe/meta.yaml 文件中的版本号。