GitHub上的SAGE存储库

Sage发展的中心是 the SageMath organization on GitHub ，它由许多与Sage相关的存储库组成。其中最重要的当然是 the Sage repository ，我们简称它为“Sage回购”。

获取GitHub帐户

要在Sage上分享您的工作，您需要一个GitHub帐户。如果您还没有用户名，请选择用户名并 create an account 。在下面，我们假定您的用户名为“Alice”。所以，如果你看到“Alice”，你总是会读到你自己的用户名。

使用GitHub CLI

GitHub提供了一个命令行界面，即GitHub CLI，可以代替Web界面使用。GitHub CLI的中心组件是 gh 您可以在您的终端中使用的命令。

安装

该页面 spkg_github_cli 文档说明如何安装 gh 用于您的平台的命令。或查看 GitHub CLI 来自GitHub的。

配置

您必须通过GitHub帐户的身份验证才能 gh 命令与GitHub交互。通常情况下，授权过程如下：

[alice@localhost sage]$ gh auth login
? What is your preferred protocol for Git operations? HTTPS
? Authenticate Git with your GitHub credentials? Yes
? How would you like to authenticate GitHub CLI? Login with a web browser

! First copy your one-time code: 3DA8-5ADA
Press Enter to open github.com in your browser...
✓ Authentication complete.
- gh config set -h github.com git_protocol https
✓ Configured git protocol
✓ Logged in as sage

其中使用Web浏览器来输入凭证。您也可以改用身份验证令牌，在这种情况下，您必须首先生成 a Personal Access Token here 。

接下来设置默认回购 gh 命令：：

[alice@localhost sage]$ gh repo set-default sagemath/sage

并勾选：

[alice@localhost sage]$ gh repo view
sagemath/sage
...

这将显示默认回购及其自述文件，这是相当长的。

gh 扩展部分

gh 是可扩展的；例如，对 gh 允许使用Docker在本地测试Sage的GitHub操作。它被称为 act 并可通过运行以下命令来安装：

[alice@localhost sage]$ gh extension install https://github.com/nektos/gh-act

附加 --force 标记添加到上面的命令，以强制升级扩展。有关配置和使用的详细信息 gh act 都在 在多个平台上测试 。

将Git链接到您的GitHub帐户

为了让您的Git与GitHub一起工作，您的GitHub帐户需要与您的Git链接。如果您已经为GitHub上的任何其他项目做出了贡献，并为此设置了Git凭据或SSH密钥，则无需执行任何操作。

以上对话来自 gh auth login 使用您的GitHub凭据通过HTTPS协议将您的Git链接到GitHub。或者，您可能希望使用Popular Git Credential Manager 它将您的凭据本地存储到您的平台。有关详细信息，请参阅 Caching your GitHub credentials in Git 。

如果您更喜欢SSH而不是HTTPS来向GitHub验证Git，那么您可以遵循 通过SSH进行Git身份验证 生成SSH密钥对并将SSH公钥添加到您的GitHub帐户。上传公钥的一种简单方法是在对话中为Git操作选择SSH协议 gh auth login 上面的命令。有关更多详细信息，请参阅 Connecting to GitHub with SSH 。

在本指南的其余部分，我们假定使用HTTPS协议。

派生Sage存储库

第一步是创建 your personal fork 在GitHub上的Sage回购。登录到您的gihub帐户后，访问Sage回购https://github.com/sagemath/sage，，只需在Sage回购上点击“分支”即可。然后，您的Sage回购分支将在https://github.com/alice/sage.创建

接下来，如果您没有Sage的本地Git资源库，则重新开始 cloning your fork ：

如果您已经有一个本地Git存储库，并且只想将您的fork链接为 origin 远程，然后执行以下操作：

您还可以添加Sage Repo sagemath/sage 作为您的遥控器 upstream ：

为了防止意外地推到 upstream (而不是 origin )，您可能想要通过运行：：

[alice@localhost sage]$ git remote set-url --push upstream DISABLE

当然，你可以随意给你的Git遥控器命名，但是 origin 和 upstream 是已建立的默认设置，这将使GitHub CLI等工具的使用变得更容易。

报告错误

如果您认为在Sage中发现了错误，则步骤如下：

• 搜索我们的谷歌群组 sage-devel ， sage-support 对于与您可能的错误相关的帖子(它可能已经修复/报告)。您还可以搜索 the GitHub issues 看看是否有其他人已经打开了关于您的错误的问题。

• 如果您没有找到任何东西，但您不确定是否发现了错误，请在 sage-devel 。

• 如果你确定你已经发现了一个错误，那么在GitHub上创建一个关于这个错误的新问题。

  错误报告应包含：

  • 一个明确的AND reproducible example 说明您的错误(和/或复制错误行为所需的步骤)。它还有助于描述预期的行为。

  • 这个 version of Sage 运行，以及错误中可能涉及的可选程序包的版本。

  • 如果相关，请描述您的 operating system 尽可能准确地了解您的CPU的体系结构(32位、64位，...)。

关注 打开一期杂志 以获得进一步的指导。提前感谢您报告错误以改进Sage！

计划增强功能

除了错误报告之外，如果你有一些新的代码或想法让Sage变得更好，你也应该打开一个问题。如果您有功能请求，请开始讨论 sage-devel 首先，如果大家似乎一致认为你有一个好主意，那就打开一个描述这个想法的问题。

在开始发行新的一期之前，请考虑以下几点：

• 确保没有其他人打开过关于相同或密切相关问题的问题(或公关)。用一些关键字搜索存在的问题和PR。

• 公开几个具体的问题比一个非常宽泛的问题要好得多。事实上，一个涉及许多不同问题的问题可能会很有问题，应该避免。

• 准确地说：如果foo不能在MacOS上运行，但在Linux上运行良好，请在标题中注明。使用关键字选项，这样搜索就可以找到问题。

• 问题中描述的问题必须是可解决的。例如，打开一个目的是“让Sage成为世界上最好的数学软件”的问题是愚蠢的。没有合适的衡量标准来衡量这一点，而且它是高度主观的。

• 如果合适，请提供与您报告的问题相关的背景信息或SAGE-DELD对话的URL。

打开一期杂志

无论是报告漏洞还是计划增强功能， issue 应在我们的SAGE回购上打开 sagemath/sage 在GitHub上。

• 想一个合适的标题。人们浏览问题的标题，以决定进一步研究哪些问题。所以，写一个标题，简明扼要地描述这个问题的内容。

• 在问题正文中详细描述问题。问题出在哪里？我们怎样才能解决这个问题？添加指向相关问题/PR和其他资源的链接。

  您可以使用GitHub提及 @USERNAME 吸引对这一问题感兴趣或对这一问题有专长的人的注意。

• 为创建的问题添加适当的标签：

  • Type 带前缀的标签 t: 比如 t: bug ， t: enhancement ， t: feature ， t: performance ， t: refactoring ， t: tests

  • Component 带前缀的标签 c: 比如 c: basic arithmetic ， c: linear algebra ， c: geometry 等

  • Priority 带前缀的标签 p: 比如 p: trivial / 5 ， p: minor / 4 ， p: major / 3 ， p: critical / 2 ，以及 p: blocker / 1

  如果这个问题预计不会在不久的将来得到解决，您可以添加 wishlist item 标签。

创建拉式请求

如果您处理了一个问题，并为错误准备了修复程序，或者编写了增强Sage的代码，那么您就在Sage Repo上创建了一个PR sagemath/sage 。

除了前面提到的关于发行一期的内容外，以下内容也适用：

• 标题应该简明扼要地描述公关的工作。如果公关解决了问题，请简要描述公关解决了什么(不要简单地将问题编号放在标题中)。

• 详细解释公关在体内解决了什么问题。如果公关解决了一个问题，你可以在这里提到这个问题。

• 添加类型、组件和优先级标签。如果此PR解决了现有问题，请将该问题的标签复制到此PR。

• Dependencies ：用这个短语 - Depends on ，后跟问题或公关参考。如果有多个依赖项，请在单独的行中重复此操作。各种依赖项管理器都能理解此格式。

如果您正在处理一份公关，而该公关还没有完全准备好进行审查，那么 open the PR as draft 。

公关的地位

如果请购单处于草稿状态，则不会启动审核流程。否则，一旦审核者对PR感兴趣，将立即开始PR的审查过程，并且PR的状态将由 status 带前缀的标签 s: 。

• s: needs review ：代码已准备好接受同行审查。如果代码不是您的，那么您可以查看它。看见 审查代码 。

• s: needs work ：代码中需要更改一些内容。原因应该出现在评论中。

• s: needs info ：公关的作者或其他人应回答问题或提供信息以继续审查过程。

• s: positive review ：PR已得到积极审查，发布经理将其合并到 develop 在适当的时候，Sage回购的分支。

如果公关没有得到正面评价，并决定关闭公关，则公关将获得以下之一 resolution 标签： r: duplicate ， r: invalid ， r: wontfix ， r: worksforme 。

权宜之计

当Sage返回错误结果时，应该创建一个问题和一个PR：

• 一个包含所有可用细节的权宜之计。

• 权宜之计的公关(例如 :issue:`12699` )

权宜之计PR没有解决问题，但添加了一个警告，每当有人使用相关代码时，都会打印该警告，直到问题最终得到解决。

要生成警告消息，请使用如下代码：

from sage.misc.stopgap import stopgap
stopgap("This code contains bugs and may be mathematically unreliable.",
    ISSUE_NUM)

替换 ISSUE_NUM 根据权宜之计问题的参考编号。在权宜之计问题上，输入权宜之计公关的参考号。权宜之计和PR应标记为关键问题。

备注

例如，如果数学上有效的代码导致Sage引发错误或崩溃，则不需要权宜之计。相反，权宜之计是为了警告用户他们可能正在使用有缺陷的代码；如果Sage崩溃，这不是问题。

评论问题和公关

任何人都可以对问题或公关发表评论。如果公关链接到某个问题，您可能不确定评论应该放在哪里。然后

• 对报告的问题的评论应该在这个问题上发表。

• 对提交的代码的评论应该放在公关上。

对PR的检查

如果你设法修复了一个错误或增强了Sage，你就是我们的英雄。看见 开发演练 用于更改Sage源代码和 创建拉式请求 为变更创建公关。

对于每一次公关推送，公关分支的自动测试都运行在GitHub操作上。

• A linting workflow 检查当前分支的代码是否符合使用 Pycodestyle (在 pycodestyle-minimal 配置)和 Relint 。

  为了在失败时查看详细信息，您可以单击检查，然后选择最新的工作流运行。

• 这个 build and test workflow 在GitHub操作上为当前分支构建SAGE(在安装 develop 分支)并运行测试。点击复选框即可查看详细信息。

  自动工作流在容器上运行，该容器基于 ubuntu-focal-standard 。要请求在不同平台上运行工作流，您可以发出 workflow dispatch 。您可以选择以下任何一种平台 prebuilt container image 是存在的。

• 这个 build documentation workflow 在GitHub操作上，构建当前分支的HTML文档。

  构建的文档的链接被添加到注释中，因此您可以轻松地检查对文档的更改，而不需要自己在本地重新构建文档。

  如果文档构建失败，您可以转到Actions选项卡并检查 documentation build workflow 并选择特定的分支机构来查看哪里出了问题。

结束语

• 修复的每一个错误都应该导致文档测试。

• 对于Sage和太少的开发人员来说，有很多可能的增强功能来实现所有好的想法。

• 如果你是一名开发人员，友善一些，偶尔试着解决一些陈旧的问题。

• 有些人定期进行分诊。在这种情况下，这意味着我们查看新的错误，并根据我们感知的优先级对它们进行分类。很可能不同的人会看到与我们非常不同的错误优先级，所以如果您看到特定PR的问题，请让我们知道。