​

逐步贡献指南

本文档包含协作开发 Nixtla 不同库的说明。

有时，深入研究一项新技术可能充满挑战且令人不知所措。我们也有过类似的经历，并且非常乐意协助您解决在遵循这些步骤时可能遇到的任何问题。请随时在 Slack 上联系我们。只需给 fede 发个消息，她会很乐意协助您。

​

目录 📚

1. 先决条件
2. Git fork-and-pull 工作流
3. 设置 Conda 环境
4. 安装所需的开发库
5. 启用可编辑模式
6. 设置基于 Notebook 的开发环境
7. 开始编码
8. 附带截图的示例

​

先决条件

• GitHub：您应该已经拥有 GitHub 账户并对其基本功能有初步了解。或者，请查阅本指南。
• Python：您的系统上应该已经安装了 Python。或者，请查阅本指南。
• conda：您需要安装 conda，并对创建、激活和停用环境等基本操作有很好的掌握。或者，请查阅本指南。

​

Git fork-and-pull 工作流

1. Fork 项目： 首先将 Nixtla 仓库 Fork 到您自己的 GitHub 账户。这将创建一份项目个人副本，您可以在其中进行更改而不会影响主仓库。

2. 克隆 Fork 的仓库： 使用 git clone https://github.com/<your-username>/nixtla.git 将 Fork 的仓库克隆到您的本地机器。这使您可以直接在您的系统上使用代码。

3. 创建分支

GitHub 中的分支是有效管理和隔离项目变更的关键策略。它允许您隔离不同功能、修复和问题上的工作，而不会干扰主体的、可用于生产的代码库。

1. 主分支：包含可用于生产代码的默认分支。

2. 功能分支：对于新功能，创建以 ‘feature/’ 为前缀的分支，例如 git checkout -b feature/new-model。

3. 修复分支：对于 Bug 修复，使用 ‘fix/’ 前缀，例如 git checkout -b fix/forecasting-bug。

4. Issue 分支：对于特定 Issue，使用 git checkout -b issue/issue-number 或 git checkout -b issue/issue-description。

测试完成后，分支会通过 Pull Request 合并回主分支，然后通常会被删除以保持仓库整洁。您可以在这里阅读更多关于 github 和分支的信息。

​

设置 Conda 环境

如果您想使用 Docker 或 Codespaces，请通过提交 Issue 告知我们，我们将为您设置好。

接下来，您需要设置一个 Conda 环境。Conda 是一个开源的包管理和环境管理系统，可在 Windows、macOS 和 Linux 上运行。它允许您创建包含文件、包和依赖项的独立环境，这些环境不会相互干扰。

首先，确保您的系统上安装了 Anaconda 或 Miniconda。或者，请查阅这些指南：Anaconda、Miniconda 和 Mamba。

然后，您可以使用 conda create -n nixtla-env python=3.10 创建一个新的环境。

您也可以使用 mamba 创建环境（mamba 比 Conda 快），使用 mamba create -n nixtla-env python=3.10。

您可以将 nixtla-env 替换为您认为更有意义的名称。例如 statsforecast-env 或 mlforecast-env。您始终可以使用 conda env list 检查系统中的环境列表。

使用 conda activate nixtla-env 激活您的新环境。

​

安装所需的开发库

environment.yml 文件包含项目所需的所有依赖项。要安装这些依赖项，请使用 mamba 包管理器，它比 Conda 提供更快的包安装和环境解析。如果您尚未安装 mamba，可以使用 conda install mamba -c conda-forge 进行安装。运行以下命令安装依赖项：

mamba env update -f environment.yml

有时（例如 StatsForecast），environment.yml 文件会位于一个名为 dev 的文件夹中。在这种情况下，您应该运行 mamba env update -f dev/environment.yml。

​

启用可编辑模式

使用 pip install -e ".[dev]" 以可编辑模式安装库。

这意味着包直接链接到源代码，允许对源代码进行的任何更改立即反映在您的 Python 环境中，而无需重新安装包。这对于包开发过程中的测试更改很有用。

​

设置基于 Notebook 的开发环境

基于 Notebook 的开发是指使用交互式 Notebook（例如 Jupyter Notebooks）进行编码、数据分析和可视化。以下是其特点的简要说明：

1. 交互性：Notebook 中的代码写在单元格中，可以独立运行。这允许对小型代码片段进行迭代开发和测试。

2. 可视化：Notebook 可以在同一界面中渲染图表、表格、图像和其他图形输出，非常适合数据探索和分析。

3. 文档化：Notebook 支持 Markdown 和 HTML，允许详细的行内文档。代码、输出和文档都在一个地方，这非常适合教程、报告或分享工作。

对于基于 Notebook 的开发，您需要 nbdev 和一个 Notebook 编辑器（例如 VS Code、Jupyter Notebook 或 Jupyter Lab）。nbdev 和 jupyter 已在上一阶段安装。如果您使用 VS Code，请遵循本教程。

nbdev 使您的代码调试和重构比传统编程环境容易得多，因为您可以随时随地访问实时对象。nbdev 也提倡软件工程最佳实践，因为测试和文档是核心要素。

您所有的更改都必须写在库中包含的 Notebooks（在 nbs 目录下）中。一旦打开特定的 Notebook（更多细节将在后续介绍），您就可以像在传统 Python 开发工作流中那样，在 Notebook 内的单元格中编写 Python 代码。您可以将复杂问题分解为更小的部分，可视化数据，并记录您的思考过程。除了代码，您还可以包含 markdown 单元格，直接在 Notebook 中添加文档。这包括对您的逻辑的解释、使用示例等。此外，nbdev 允许您在 Notebook 中与代码内联编写测试。编写完一个函数后，您可以立即在后续单元格中为其编写测试。

代码准备就绪后，nbdev 可以自动将您的 Notebook 转换为 Python 脚本。代码单元格转换为 Python 代码，markdown 单元格转换为注释和文档字符串。

​

开始编码

使用 jupyter lab（或 VS Code）打开 jupyter notebook。

1. 进行您的更改：对代码库进行更改，确保您的更改是自包含且一致的。

2. 提交您的更改：使用 git add [your_modified_file_0.ipynb] [your_modified_file_1.ipynb] 添加更改的文件，然后使用 git commit -m "<type>: <您的描述性提交消息>" 提交这些更改。请使用Conventional Commits

3. 推送您的更改：使用 git push origin feature/your-feature-name 将您的更改推送到 GitHub 上的远程仓库。

4. 打开 Pull Request： 在 GitHub 上的 Nixtla 仓库中，从您的新分支打开一个 Pull Request。在创建 Pull Request 时，请提供对您的更改的详细描述。

5. 等待审查： Nixtla 项目的维护者将审查您的更改。准备好根据他们的反馈对您的贡献进行迭代修改。

记住，为开源项目做贡献是一项协作努力。尊重他人的工作，欢迎反馈，并始终努力改进。祝您编码愉快！

Nixtla 提供了为贡献者提供计算基础设施津贴的可能性。如果您感兴趣，请加入我们的 slack 并联系 fede 或 Max。

您可以在下面找到附带截图的详细逐步指南。

​

附带截图的示例

​

1. Fork mlforecast 仓库

您首先需要做的就是将 GitHub 仓库 Fork 到您自己的账户下

您的账户上的 Fork 仓库将如下所示

在该仓库中，您可以进行更改，然后请求将更改添加到主仓库。

​

2. 克隆仓库

在本教程中，我们使用 Mac（也兼容其他 Linux 发行版）。如果您是 Nixtla 的协作贡献者，您可以申请一个 AWS 实例在那里进行协作。如果是这种情况，请在 Slack 上联系 Max 或 Fede 以获得相应的访问权限。我们还使用 Visual Studio Code，您可以从此处下载。

创建仓库后，您需要将其克隆到自己的计算机上。只需复制 GitHub 上的仓库 URL，如下所示

然后打开 Visual Studio Code，点击“克隆 Git 仓库”，并将您刚刚复制的行粘贴到窗口顶部，如下所示

选择您要复制仓库的文件夹

并选择打开克隆的仓库

您将得到类似如下所示的内容

​

3. 创建 Conda 环境

在 Visual Studio Code 中打开一个终端，如图片所示

您可以使用 conda，但我们强烈建议使用 Mamba 来加快 Conda 环境的创建速度。要安装它，只需在您刚刚打开的终端中使用 conda install mamba -c conda-forge

使用以下命令创建一个名为 mlforecast 的空环境：mamba create -n mlforecast python=3.10

使用 conda activate mlforecast 激活新创建的环境

使用命令 mamba env update -f environment.yml 在环境文件 environment.yml 中安装库

现在使用 pip install -e ".[dev]" 安装库，以便进行交互式更改和其他附加依赖项

​

4. 进行您想要的更改。

在本节中，我们假设要将用于创建预测区间（prediction intervals）的默认窗口数从 2 增加到 3。首先需要做的就是使用 git checkout -b [new_branch] 创建一个专门针对该更改的分支，如下所示

创建完成后，打开您想要修改的 notebook。在本例中，它是 nbs/utils.ipynb，其中包含预测区间的元数据。打开后，点击您想要使用的环境（右上角）并选择 mlforecast 环境

接下来，执行 notebook 并进行必要的更改。在本例中，我们要修改 PredictionIntervals 类

我们将把 n_window 的默认值从 2 修改为 3

完成更改并执行必要的验证后，就可以将 notebook 转换为 Python 模块了。为此，只需在终端中使用 nbdev_export。

您将看到 mlforecast/utils.py 文件已被修改（来自 nbs/utils.ipynb 的更改反映在该模块中）。在提交更改之前，我们需要使用命令 ./action_files/clean_nbs 清理 notebook，并使用 ./action_files/lint 验证 linter 是否通过。

完成上述操作后，只需使用 git add nbs/utils.ipynb mlforecast/utils.py 添加更改。

使用 git commit -m "[更改描述]" 为更改创建一个描述性的提交消息。

最后，使用 git push 推送您的更改。

​

5. 创建 Pull Request。

在 GitHub 中，打开包含您 Fork 的原始仓库的仓库。进入后，您将看到刚刚推送的更改。点击“Compare and pull request”（比较并拉取请求）

为您的 Pull Request 提供一个合适的标题，并填写必要的信息。完成后，点击“Create pull request”（创建拉取请求）。

最后，您将看到类似如下的内容

​

注意

• 此文件是使用此文件生成的。如果您想改进此文档，请更改该文件。