维护者说明¶

这是针对具有上游读写权限的人员。建议将上游远程命名为一些东西，以提醒您它是读写权限的

git remote add upstream-rw git@github.com:statsmodels/statsmodels.git
git fetch upstream-rw

Git 工作流¶

获取来自他人的更改¶

如果您需要推送来自他人的更改，您可以通过以下方式链接到他们的存储库

git remote add contrib-name git://github.com/contrib-name/statsmodels.git
get fetch contrib-name
git branch shiny-new-feature --track contrib-name/shiny-new-feature
git checkout shiny-new-feature

以下内容假设您位于您自己或其他人的分支上，其中包含您要推送到上游的更改。

变基¶

如果只有几个提交，您可以变基以保持线性历史记录

git fetch upstream-rw
git rebase upstream-rw/main

但是，变基不会自动关闭拉取请求（如果有），因此请不要忘记这样做。

合并¶

如果有一系列相关的提交，那么您需要合并。您可能会问自己，合并：快进还是不快进？请参阅以下有关此选择的更多信息。一旦决定，您可以执行以下操作

git fetch upstream-rw
git merge --no-ff upstream-rw/main

合并将自动关闭 github 上的拉取请求。

检查历史记录¶

这一点非常重要。再次强调，所有修复都应在本地进行，然后再推送到存储库

git log --oneline --graph

这以一种紧凑的方式显示了当前分支的历史记录。这

git log -p upstream-rw/main..

显示了提交日志，不包括可以从 upstream-rw/main 访问的提交，包括可以从当前 HEAD 访问的提交。也就是说，这些更改是此分支相对于 upstream-rw/main 的唯一更改。有关在日志中使用点以及在 diff 中使用点 的更多信息，请参阅 Pydagogue。

推送您的功能分支¶

所有更改看起来都很好吗？您可以在 合并 或 变基 后推送您的功能分支

git push upstream-rw shiny-new-feature:main

樱桃-选择¶

假设您对另一个分支中的某个提交感兴趣，但现在想保留其他提交。您可以使用樱桃选择来做到这一点。使用 git log –oneline 查找要樱桃选择的提交。假设您想要来自 shiny-new-feature 分支的提交 dd9ff35。您想将此提交应用到 main。您只需执行以下操作

git checkout main
git cherry-pick dd9ff35

就这样。此提交现在作为 main 中的一个新提交被应用。

合并：快进还是不快进¶

默认情况下，git merge 是一个快进合并。这意味着什么，以及何时要避免这种情况？

快进合并不会创建合并提交。这意味着功能分支的存在在历史记录中丢失了。快进是 Git 的默认设置，主要是因为分支很便宜，因此通常是短暂的。另一方面，如果您有一个长期存在的特征分支，或者正在特征分支上遵循迭代工作流（即合并到 main，然后返回特征分支并添加更多提交），那么只有合并到 main 分支中是有意义的，而不是所有中间特征分支提交，因此您应该使用

git merge --no-ff

处理拉取请求¶

您可以通过 fetch 和 merge 来应用拉取请求。在您的 main 仓库本地副本中

git checkout main
git remote add contrib-name git://github.com/contrib-name/statsmodels.git
git fetch contrib-name
git merge contrib-name/shiny-new-feature

检查合并是否干净地应用，并且历史记录看起来不错。编辑合并消息。添加一个简短的说明，说明该分支做了什么，以及一个“Closes gh-XXX。”字符串。这将自动关闭拉取请求，并将票证和关闭提交链接起来。要自动关闭问题，您可以在提交消息中使用以下任何内容

gh-XXX
GH-XXX
#XXX

在进行以下操作之前，需要在本地处理所有问题

git push origin main

发布¶

1. 检出 main

   git checkout statsmodels/main
   

2. 使用以下命令清理工作树

   git clean -xdf
   

   但是您可能想先进行干运行

   git clean -xdfn
   

3. 本地标记发布。例如，对于发布候选版本

   git tag -a v0.10.0rc1 -m "Version 0.10.0 Release Candidate 1" 7b2fb29
   

   或者只是

   git tag -a v0.10.0rc1 -m "Version 0.10.0 Release Candidate 1"
   

   以使用 main 中的最后一个提交。

4. 检出标签

   git checkout tags/v0.10.0rc1
   

5. 构建一个 sdist 以确保构建是干净的

   python -m build --sdist .
   

   tar.gz 文件上的构建必须与标签相同，这一点很重要。它不能是脏的

6. 如果在新的次要版本（major.minor.micro 格式）上，则启动一个新的维护分支，例如

   git checkout -b maintenance/0.10.x
   

   任何针对下一个微版本发布的错误修复和维护提交都应像往常一样针对 main 进行，但应使用它所属的微版本的里程碑进行标记。然后像往常一样合并到 main。准备好进行回退时，使用文件 tools/backport_pr.py 来识别哪些 PR 需要回退以及将其应用到维护分支。该版本的标签应在维护分支中创建。

7. 将源代码分发上传到 PyPI

   twine upload dist/*
   

   您可能想先上传到测试

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

8. 返回 main 分支，并添加一个空提交

   git checkout statsmodels/main
   git commit --allow-empty -m "Start of 0.11.0 development"
   git tag -a v0.11.0.dev0 -m "Start of 0.11.0 development"
   

9. 将所有内容推送到 statsmodels

   git push --tags
   

   如果创建了新分支

   git push --set-upstream origin maintenance/0.10.x
   

10. 发布公告，并告知轮子构建器。

11. 盈利？

从维护分支发布¶

一旦任何补丁都已回退到维护分支，发布步骤如下

1. 检出分支

   git checkout maintenance/0.10.x
   

2. 彻底清理

   git clean -xdf
   

3. 本地标记发布

   git tag -a v0.10.0 -m "Version 0.10.0"
   

4. 检出标签

   git checkout tags/v0.10.0
   

5. 构建一个 sdist 以确保构建是干净的

   python -m build --sdist .
   

   tar.gz 文件上的构建必须与标签相同，这一点很重要。它不能是脏的。

6. 将源代码分发上传到 PyPI 或 PyPI 测试

   twine upload dist/*
   

   或

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

7. 将标签推送到 statsmodels

   git push --tags
   

8. 发布公告，并告知轮子构建器。

提交注释¶

在主共享存储库的 main 分支中，提交消息前缀应为以下内容

ENH: Feature implementation
BUG: Bug fix
STY: Coding style changes (indenting, braces, code cleanup)
DOC: Sphinx documentation, docstring, or comment changes
CMP: Compiled code issues, regenerating C code with Cython, etc.
REL: Release related commit
TST: Change to a test, adding a test. Only used if not directly related to a bug.
REF: Refactoring changes