为 Eland 贡献力量#

Eland 是一个开源项目，我们很乐意收到来自社区的贡献——您！您可以通过多种方式贡献，例如编写教程或博客文章、改进文档、提交错误报告和功能请求，或者编写可以集成到 eland 本身的代码。

错误报告#

如果您认为在 eland 中发现了错误，请首先确保您正在针对最新版本的 eland进行测试——您的问题可能已经解决。如果不是，请搜索我们GitHub 上的问题列表，以防类似问题已经打开。

如果您能准备一个错误的重现，那就非常有帮助。换句话说，提供一个我们可以运行的小型测试用例来确认您的错误。这将使我们更容易找到问题并解决它。测试用例应作为 python 脚本提供，最好附带一些关于您的 Elasticsearch 环境和索引映射的详细信息，以及（在适当情况下）一个 pandas 示例。

提供尽可能多的信息。您可能会认为问题出在您的查询上，而实际上它取决于您的数据是如何索引的。我们越容易重现您的问题，它就越有可能被快速解决。

功能请求#

如果您发现自己想要一个 eland 中不存在的功能，您可能并不孤单。一定还有其他人在那里有类似的需求。Eland 今天拥有的许多功能都是因为我们的用户看到了需求而添加的。在我们的GitHub 上的问题列表中打开一个问题，描述您希望看到的功能、您需要它的原因以及它应该如何工作。

贡献代码和文档更改#

如果您有一个要贡献给 eland 的错误修复或新功能，请先找到或打开一个关于它的问题。谈谈您想做什么。可能是有人已经在做这件事了，或者您在实施更改之前应该了解一些特定问题。

我们乐于与贡献者合作，让他们的代码被接受。解决问题的方法有很多，在编写太多代码之前，找到最佳方法很重要。

请注意，项目不太可能合并为了重构而进行的重构。这类 pull 请求对维护者来说，在审查和测试方面成本很高，而实际利益却很少。这尤其包括由工具生成的更改。

为任何Elastic 存储库贡献代码的过程都是类似的。有关各个项目的详细信息，请参见下方。

分叉并克隆存储库#

您需要分叉主要的 eland 代码或文档存储库并将其克隆到您的本地机器。参见Github 分叉存储库页面 - 以获得帮助。

有关特定项目的进一步说明，请参见下方。

提交更改#

您的更改和测试准备提交以供审查后

  1. 运行 linter 和测试套件以确保您的更改不会破坏现有代码：（TODO 添加指向测试文档的链接）

    # Run Auto-format, lint, mypy type checker for your changes
$ nox -s format

# Run the test suite
$ pytest --doctest-modules eland/ tests/
$ pytest --nbval tests/notebook/

  2. 签署贡献者许可协议

    请确保您已签署我们的贡献者许可协议。我们不是要求您将版权转让给我们，而是要求您给予我们无限制分发您代码的权利。我们要求所有贡献者这样做，以向我们的用户保证代码的来源和持续存在。您只需签署一次 CLA 即可。

  3. 变基您的更改

    使用主 eland 存储库中的最新代码更新您的本地存储库，并将您的分支变基到最新的主分支上。我们更希望您的初始更改被压缩成一个提交。稍后，如果您要求您进行更改，请将其添加为单独的提交。这将使它们更容易审查。作为合并前的最后一步，我们将要求您自己压缩所有提交，或者我们为您完成。

  4. 提交 pull 请求

    将您的本地更改推送到您分叉的存储库副本，并提交 pull 请求。在 pull 请求中，选择一个标题来概括您所做的更改，并在正文中提供有关您的更改所做工作的更多详细信息。还请提及讨论过的地方的问题编号，例如“Closes #123”。

然后坐下来等待。关于 pull 请求可能会有讨论，如果有任何需要更改的地方，我们很乐意与您合作，将您的 pull 请求合并到eland中。

请遵守一般准则，即您不应该强制推送到公共共享分支。一旦您打开了 pull 请求，您应该认为您的分支是公开共享的。您可以只添加增量提交，而不是强制推送到分支；这通常对您的审阅者来说更容易。如果您需要从主分支获取更改，您可以将主分支合并到您的分支。审阅者可能会要求您变基一个长期运行的 pull 请求，在这种情况下，强制推送到该请求是可以的。请注意，在审查过程结束时不应该进行压缩，这可以在通过 GitHub集成 pull 请求时完成。

为 eland 代码库贡献力量#

存储库：https://github.com/elastic/eland

我们在内部使用 PyCharm IDE 进行开发。对于 PyCharm，我们目前使用的是 PyCharm 2019.2.4 的最低版本。

配置 PyCharm 和运行测试#

（所有命令都应该从模块根目录运行）

  • 通过“从版本控制签出”创建新项目

    在“欢迎使用 PyCharm”页面上点击“控制”->“Git” <或其他>

  • 输入您分叉的 eland 的 URL

    <例如 [email protected]:stevedodson/eland.git>

  • 点击“是”以“从版本控制签出”

  • 配置 PyCharm 环境

    在“首选项”中，配置一个“项目：eland”->“项目解释器”。通常，我们建议创建一个虚拟环境。（TODO 链接到安装以获得 python 版本支持）

  • 在“首选项”中，设置“工具”->“Python 集成

    工具”->“默认测试运行器”设置为pytest

  • 在“首选项”中，设置“工具”->“Python 集成

    工具”->“文档字符串格式”设置为numpy

  • 安装开发需求。在虚拟环境中打开终端并运行
    pip install -r requirements-dev.txt
  • 使用 docker 设置 Elasticsearch 实例
    ELASTICSEARCH_VERSION=elasticsearch:7.x-SNAPSHOT .ci/run-elasticsearch.sh`

  • 检查http://localhost:9200以验证 ElasticSearch 实例是否正在运行。

  • 安装本地eland模块 <需要执行笔记本测试>
    python setup.py install
  • 要设置测试环境 - *注意，这会修改 Elasticsearch 索引* 运行
    python -m tests.setup_tests
  • 要验证安装，请打开 python 控制台并运行
    import eland as ed
ed_df = ed.DataFrame('localhost', 'flights')
  • 要运行自动格式化程序并检查 lint 问题
    run `nox -s format`
  • 要测试特定版本的 Python，请运行
    nox -s test-3.8

文档#

  • 在您的系统上安装 pandoc -
    # For Ubuntu or Debian
sudo apt-get install -y pandoc
  • 安装文档需求。在虚拟环境中打开终端并运行
    pip install -r docs/requirements-docs.txt
  • 要验证/生成文档，请运行
    nox -s docs