2023 更新： 我们在这篇博文中讨论了我们对 Prophet 未来发展的计划：facebook/prophet 在 2023 年及以后

Prophet 没有固定的发布周期，但我们会根据用户反馈进行错误修复并添加功能。如果您遇到错误，请提交问题告知我们。Github 问题也是询问有关使用 Prophet 的问题的好地方。

我们感谢所有贡献。如果您计划贡献错误修复，请在无需进一步讨论的情况下进行。

如果您计划向核心贡献新功能或扩展，请首先打开一个问题并与我们讨论该功能。发送 pull request 也可以，但如果在问题中预先确定了任何设计决策，它可能会更快地合并。

我们尝试保持 R 和 Python 版本的特性相同，但可以在单独的提交中为每种方法实现新特性。

以下部分将描述如何提交 pull request 以将增强功能、文档更改或错误修复添加到代码库。

1. Fork Prophet 仓库

您需要自己的 fork 才能处理代码。转到 prophet 项目页面并点击 Fork 按钮。您需要将您的 fork 克隆到您的机器

1
2
3

$ git clone https://github.com/your-user-name/prophet.git
$ cd prophet
$ git remote add upstream https://github.com/facebook/prophet.git

这将创建目录 prophet 并将您的存储库连接到上游（主项目）prophet 存储库。

2. 创建具有依赖项的环境

在开始任何开发之前，您需要创建一个独立的 prophet 开发环境。这应该包含所需的依赖项。

Python

  • 安装 Anaconda anaconda 或 miniconda
  • 确保您的 conda 是最新的 (conda update conda)
  • cd 到您已克隆的 *prophet* 源代码目录
1
2
3
4
5
6
7
8
9

$ cd python

# with Anaconda
$ conda create -n prophet
$ conda activate prophet

# with venv
$ python3 -m venv prophet
$ source prophet/bin/activate

R

依赖项可以通过 Packrat 或 renv 进行管理。

对于 renv，您必须首先初始化一个新的项目本地环境。

1
2
3

> setwd("path/to/prophet/R") # set R subdirectory as working directory
> install.packages('renv')
> renv::init()

这也应该自动安装 DESCRIPTION 中列出的依赖项。任何新的 R 包都可以在项目中根据需要安装。

您可以保存项目状态

1

> renv::snapshot()

或加载环境

1

> renv::restore()

3. 构建 Prophet 的开发版本

下一步是在您刚创建的环境中构建并安装 prophet 的开发版本。

Python

1

$ python -m pip install -e ".[dev,parallel]"

您应该能够从本地构建的版本导入 *prophet*

1
2
3
4

$ python  # start an interpreter
>>> import prophet
>>> prophet.__version__
'1.1.2'  # whatever the current github version is

这将创建新环境，并且不会触及任何现有环境或任何现有 Python 安装。

1
2
3
4
5

# to view your environments:
$ conda info -e

# to return to your root environment::
$ conda deactivate

请参阅完整的 conda 文档 here。

R

从终端，cd 到 R 子目录并运行

1

$ R CMD INSTALL .

这将构建并安装 prophet 包的本地版本。然后从 R 控制台，您可以加载该包：library(prophet)。

4. 创建分支

您希望您的 main 分支仅反映生产就绪的代码，因此创建一个特性分支来进行更改。例如

1

$ git checkout -b new-feature

这会将您的工作目录更改为 new-feature 分支。将此分支中的任何更改都保持为一个错误或特性，以便清楚该分支为 *prophet* 带来了什么。您可以有许多“新特性”，并使用 git checkout 命令在它们之间切换。

要更新此分支，您需要从 main 分支检索更改

1
2

$ git fetch upstream
$ git rebase upstream/main

这将在最新的 *prophet* git main 之上重放您的提交。如果这导致合并冲突，您必须在提交 pull request 之前解决这些冲突。如果您有未提交的更改，您将需要 git stash 它们才能更新。这将有效地存储您的更改，并且可以在更新后重新应用它们。

5. 使用持续集成进行测试

在将代码推送到 prophet 后，添加测试是最常见的请求之一。因此，养成提前编写测试的习惯是值得的，这样就不会出现问题。一旦您的 pull request 被提交，Github Actions CI（持续集成）服务会自动触发 Prophet 的 Python 和 R 构建并运行测试。当您拥有全部“绿色”构建时，将考虑合并 pull request。如果任何测试失败，您将得到一个红色“X”，您可以点击查看各个失败的测试。

Python

Prophet 使用 pytest 包在 Python 中运行测试，并使用 testthat 包在 R 中进行测试。所有测试都应进入 Python 或 R 文件夹中的 tests 子目录。

可以通过键入以下内容来运行整个测试套件

1

$ python -m pytest prophet/tests/

R

可以通过安装 devtools 从 R 控制台运行整个测试套件

1
2

> install.packages('devtools')
> devtools::test()

或者，在 cd 到 tests 目录后，也可以从终端运行测试套件

1

$ Rscript testthat.R

或者，对于仅从 R 控制台运行单个测试脚本（如 test_diagnostics.R）

1
2

> library(testthat)
> source('test_diagnostics.R')

6. 生成文档

大多数 doc 页面都是从源代码树底部的 notebooks 目录中的 Jupyter notebooks 生成的。请在那里进行更改，然后重建文档

1
2

$ cd docs
$ make notebooks

确保您已安装 rpy2，以便也可以运行 R 代码。

在 R 中，如果添加了新参数或创建了新函数，还必须生成源代码的文档。这是使用 roxygen 记录的。

在提交对 R 代码进行任何更改的 PR 之前运行以下命令来更新函数文档

1

> devtools::document()

7. 提交您的代码

将样式修复保留在单独的提交中，以使您的 pull request 更易读。完成更改后，您可以通过键入以下内容来查看它们

1

$ git status

如果您创建了一个新文件，则 git 不会跟踪它。通过键入以下内容来添加它

1

$ git add path/to/file-to-be-added.py

再次执行“git status”应该会得到类似的结果

1
2
3
4

# On branch new-feature
#
#       modified:   /relative/path/to/file-you-added.py
#

现在您可以在本地存储库中提交您的更改

1

$ git commit -m

8. 推送您的更改

当您希望您的更改公开显示在您的 GitHub 页面上时，推送您的 fork 特性分支的提交

1

$ git push origin new-feature

这里 origin 是 GitHub 上您的远程存储库的默认名称。您可以查看远程存储库

1

$ git remote -v

如果您按照上述说明添加了上游存储库，您将看到类似的内容

1
2
3
4

origin  git@github.com:yourname/prophet.git (fetch)
origin  git@github.com:yourname/prophet.git (push)
upstream	https://github.com/facebook/prophet.git (fetch)
upstream	https://github.com/facebook/prophet.git (push)

现在您的代码在 GitHub 上，但它还不是 prophet 项目的一部分。为此，需要在 GitHub 上提交 pull request。

9. 审查您的代码

当您准备好请求代码审查时，请提交 pull request。在您这样做之前，请再次确保您已遵循本文档中概述的所有关于代码风格、测试、性能测试和文档的指南。您还应该根据其所基于的分支仔细检查您的分支更改

  1. 导航到您在 GitHub 上的存储库 – https://github.com/your-user-name/prophet
  2. 点击 Branches
  3. 点击您的特性分支的 Compare 按钮
  4. 如果需要，选择基本分支和比较分支。这分别是 main 和 new-feature。

10. 提交 pull request

如果一切看起来正常，您就可以发起一个 pull request（拉取请求）。Pull request 使得本地仓库中的代码可以被 GitHub 社区使用，并可以被审查，最终合并到 main 版本中。此 pull request 及其相关的更改最终将被提交到 main 分支，并在下一个版本中可用。要提交 pull request，请

  1. 导航到 GitHub 上的您的仓库
  2. 点击 Pull Request 按钮
  3. 然后，您可以点击 Commits（提交）和 Files Changed（文件更改）来最后一次确保一切正常
  4. 在 Preview Discussion（预览讨论）选项卡中编写对您的更改的描述
  5. 点击 Send Pull Request（发送 Pull Request）。

该请求随后将发送给仓库维护者，他们将审查代码。如果您需要进行更多更改，可以在您的分支中进行更改，将其添加到新的提交中，将其推送到 GitHub，并且 pull request 将自动更新。再次推送到 GitHub 的方式是

1

$ git push origin new-feature

这将自动使用最新的代码更新您的 pull request 并重新启动持续集成测试。

11. 删除您已合并的分支

一旦您的功能分支合并到 upstream main 中，您可以通过 PR 中的 Delete branch 选项删除您的远程分支，并通过运行以下命令删除本地副本

1

$ git branch -d new-feature

12. PR 检查清单

  • 为包含的任何函数编写文档字符串（docstrings）。
  • 测试文档是否正确构建。请参阅“生成文档”。
  • 测试您的代码。
    • 如果需要，编写新的测试。请参阅“使用持续集成进行测试”
    • 使用 unittest 测试代码。运行所有测试需要一段时间，因此您可以根据您的 PR 随意只运行您认为需要的测试。CI 将捕获任何失败的测试。
  • 在 R 中，您还可以运行 devtools:check() 以一次执行多个自动检查，以检查代码问题、文档、测试、包结构、小插曲等。这需要几分钟才能运行。
  • 一旦你推送了你的修改并创建了一个PR，请确保使用一个信息丰富的标题来总结你所做的修改。
  • 如果 PR 解决了一个 issue，请引用它，例如 fixes #1234

在 GitHub 上编辑