Sage-Trac服务器

对Sage源代码的所有更改都必须经过 Sage Trac development server . Sage-trac服务器的作用是

1. 提供讨论问题的场所并保存永久记录。

2. 提供源代码和所有建议更改的存储库。

3. 把这两者联系起来。

还有一个 wiki 对于更一般的组织网页，如Sage开发研讨会。

因此，如果您在Sage中发现了一个bug，如果您有新的代码要提交，想要查看已经编写但尚未包含在Sage中的新代码，或者如果您对文档有更正，您应该在trac服务器上发布。服务器上的项被调用 门票 ，任何人都可以搜索或浏览门票。有关最近更改的列表，请访问 Sage trac timeline .

取得帐户

New: 以前，有必要手动请求一个Trac帐户，以便将任何内容过帐到Sage的Trac。现在，如果您有一个GitHub帐户，您可以使用它来创建和评论罚单，并在Sage的Trac上编辑wiki页面。

目前只有当您不想使用GitHub或想登录到旧版时，才需要手动帐户请求 Sage Wiki . 这在未来也可能改变。

若要获取非GitHub帐户，请发送电子邮件至 sage-trac-account@googlegroups.com 包含：

• 你的全名，

• 首选用户名，

• 联系电子邮件，

• 以及需要trac帐户的原因

您的trac帐户还授予您访问 sage wiki . 在进行更改之前，请确保您了解审核流程以及打开和关闭票据的程序。本章的其余部分包含有关使用trac服务器的各种指南。

通过SSH进行Trac身份验证

有两种方法可以向trac服务器证明您就是您声称的自己。首先，要更改票证网页，您需要使用用户名/密码登录到trac。其次，git在将新的源文件复制到存储库时使用了公钥加密技术。本节将向您展示如何设置两者。

生成并上载SSH密钥

开发服务器上的git安装使用SSH密钥来决定是否允许以及在哪里上载代码。报告bug或对罚单的评论不需要SSH密钥，但是一旦您想自己贡献代码，您就需要向trac提供您个人密钥的公共一半。以下两个部分描述了详细信息。

生成SSH密钥

如果您还没有私钥，可以使用 ssh-keygen 工具：

[user@localhost ~]$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/user/.ssh/id_rsa.
Your public key has been saved in /home/user/.ssh/id_rsa.pub.
The key fingerprint is:
ce:32:b3:de:38:56:80:c9:11:f0:b3:88:f2:1c:89:0a user@localhost
The key's randomart image is:
+--[ RSA 2048]----+
|  ....           |
|   ..            |
|   .o+           |
| o o+o.          |
|E + .  .S        |
|+o .   o.        |
|. o   +.o        |
|      oB         |
|     o+..        |
+-----------------+

这将在 .ssh 主目录中的文件夹。默认情况下，它们是

~/.ssh/id_rsa

你的私钥。注意安全。 从未 把它发给任何人。

~/.ssh/id_rsa.pub

相应的公钥。只有此文件才能安全地披露给第三方。

这个 ssh-keygen 该工具将允许您生成具有不同文件名的密钥，或使用密码短语保护它。根据您对自己的计算机或系统管理员的信任程度，您可以将密码短语留空，以便能够在没有任何人为干预的情况下登录。

如果您在多台计算机上有帐户，则可以使用SSH密钥登录。只需复制 公众的 密钥文件（以结尾 .pub 到 ~/.ssh/authorized_keys 在远程计算机上，并确保该文件只能由您自己读/写。喂，下次你用ssh连接到那台机器时，你不需要提供密码。

将您的公钥链接到您的Trac帐户

Sage-trac服务器需要知道您的一个公钥。你可以在首选项中上传，也就是说

1. 去https://trac.sagemath.org

2. 使用您的trac用户名/密码登录

3. 点击“首选项”

4. 转到“SSH Keys”选项卡

5. 粘贴公钥文件的内容（例如。 ~/.ssh/id_rsa.pub ）

6. 单击“保存更改”

注意这是 not 允许您通过ssh登录trac上的任何帐户，它仅用于验证您是否在trac上安装gitolite。您可以通过发出一些基本的gitolite命令来测试您是否被正确地认证，例如：

[user@localhost ~]$ ssh git@trac.sagemath.org info
hello user, this is git@trac running gitolite3 (unknown) on git 1.7.9.5

 R W      sage
[user@localhost ~]$ ssh git@trac.sagemath.org help
hello user, this is gitolite3 (unknown) on git 1.7.9.5

list of remote commands available:

    desc
    help
    info
    perms
    writable

报告Bug

如果您认为在Sage中发现了错误，请执行以下步骤：

• 在我们的谷歌群组中搜索与您可能的错误相关的帖子（可能已经修复/报告）：

  • sage-devel: https://groups.google.com/group/sage-devel

  • sage-support: https://groups.google.com/group/sage-support

  同样，您可以搜索 Sage-Trac服务器 看看是否有人对你的bug开了罚单。

• 如果您没有发现任何东西，并且您不确定是否找到了bug，请在 sage-devel . 错误报告应包含：

  • 一个明确的和 可复制示例 说明您的bug（和/或重现bug行为所需的步骤）。

  • 这个 版本 您运行的Sage的版本，以及可能涉及bug的可选包的版本。

  • 描述您的 操作系统 尽可能准确地描述您的体系结构（32位、64位等）。

• 你可能会被要求开一张新票。在这种情况下，请遵循 开票指南 .

提前感谢您报告错误，以提高Sage的未来！

开票指南

除了错误报告（请参见 报告Bug )，如果您有一些新代码使Sage成为一个更好的工具，您也应该开罚单。如果您有功能请求，请开始讨论 sage-devel 首先，如果大家都认为你有一个好主意，那么就开一张罚单来描述这个想法。

• 你已经有了吗 trac帐户 ? 如果没有， click here .

之前 打开新罚单时，请考虑以下几点：

• 确保没有其他人对相同或密切相关的问题开罚单。

• 开几张特别的票比开一张很宽的票要好得多。事实上，一张涉及许多不同问题的单张罚单可能会有相当大的问题，应该避免。

• 准确点：如果foo不能在osx上工作，但在Linux上可以，那么在标题中提到这一点。使用keyword选项，这样搜索就会发现问题。

• 罚单上描述的问题必须是可以解决的。例如，开一张目的是“使Sage成为世界上最好的数学软件”的罚单是愚蠢的。没有一个标准来衡量这一点，这是高度主观的。

• 对于bug报告：票据的描述应该包含在中描述的信息 报告Bug .

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

创建时 这张票，你可能会觉得有用 售票区 .

除非您知道自己在做什么，否则请将“里程碑”字段保留为其默认值。

售票区

当您打开新记录单或更改现有记录单时，您会发现可以更改的各种字段。这里是一个全面的概述（有关“状态”字段，请参见 票证的状态 ）：

• 报告人： 创建票证的人的trac帐户名。无法更改。

• 所有者： 所有者的Trac帐户名，默认情况下是组件的负责人（见下文）。一般不用于Sage。

• 类型： 什么之中的一个 enhancement （例如，新功能）， defect （例如错误修复），或 task （很少使用）。

• 优先： 票的优先级。请记住，“拦截器”标签应尽量少用。

• 里程碑： 里程碑通常是在为发布而工作时要达到的目标。在Sage的trac中，我们使用里程碑而不是发布。每张票都必须有一个里程碑。如果不确定，请将其指定给当前里程碑。

• 组件： 一个Sage组件的列表，选择一个最匹配的问题。

• 关键词： 关键字列表。填写任何你认为可以让你的票更容易找到的关键字。在Sage节上制作的票 NN （一些人）经常 sdNN 作为关键字。

• Cc: 将trac用户名列表发送到Cc（发送电子邮件以获取票证更改）。请注意，输入评论的用户会自动添加到电子邮件更新中，不需要在Cc下列出。

• 合并地点： 票证合并的Sage版本。仅由发布管理器更改。

• 作者： 票证作者的真实姓名。

• 审核人： 检票员的真实姓名。

• 上游报告： 如果上游开发人员在这个字段中使用了一个bug来总结这个bug的上游组件。

• 工作问题： 在工单离开“需要工作”状态之前需要解决的问题。

• 分支机构： 包含票证代码的Git分支（请参见 分出 ). 它以绿色显示，除非分支与最新的beta版本（红色）有冲突。在这种情况下，应该合并分支或重新建立分支基。

• 依赖项： 这张票和另一张票有关吗？有时，一张罚单需要先申请另一张罚单。如果是这种情况，请将依赖项放在逗号分隔的列表中 (#1234, #5678 )进入“Dependencies:”字段。

• 权宜之计： 见 权宜之计 .

票证的状态

票证的状态显示在其号码旁边，在页面的左上角。它指明了谁必须为之努力。

• new --票证只创建了（或者作者忘记将状态更改为其他状态）。

  如果你想自己动手，最好留下评论说出来。它可以避免两个人做同样的工作。

• needs_review --代码已准备好接受同行评审。如果代码不是你的，那么你可以检查它。看到了吗 审阅者的检查表 .

• needs_work --代码中有些地方需要修改。原因应该出现在评论中。

• needs_info --在其他事情发生之前必须有人回答问题。从评论中应该可以清楚地看到。

• positive_review --票证已审核，发行经理将关闭它。

可以使用票据页面底部的表单更改票据的状态。在你改变的时候留下一条解释你原因的评论。

权宜之计

当Sage返回错误结果时，应打开两张罚单：

• 一张有所有可用细节的主票。

• “权宜之计”票（例如。 :trac:`12699` ）

第二个问题并不能解决问题，但是添加了一个警告，当任何人使用相关代码时，该警告将被打印出来。直到问题最终解决。

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

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

替换 TICKET_NUM 按主票的票号。在main trac票证上，在“Stopgaps”字段中输入临时通行证的票号（请参见 售票区 ). 临时通行证应标记为阻塞物。

注解

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

处理票证

如果你成功地修复了一个错误或增强了Sage，你就是我们的英雄。看到了吗 Sage开发过程 对Sage源代码进行更改，将它们上载到Sage-trac服务器，最后将您的新分支放在trac票证上。以下是一些其他相关问题：

• 补丁buildbot会自动测试您的票证。看到了吗 the patchbot wiki 有关其功能和限制的详细信息。一定要查看日志，尤其是当补丁buildbot没有给你绿色斑点的时候。

• 修复的每一个错误都会导致doctest。

• 这并不是一个缺陷问题，但是Sage有很多增强功能，而实现所有好主意的开发人员太少了。trac服务器对于将想法放在中心位置是很有用的，因为在Google组中，一旦他们放弃第一页，他们往往会迷失方向。

• 如果你是一个开发人员，要友善，偶尔尝试解决一个过时/旧的问题。

• 有些人经常进行分类。在这种情况下，这意味着我们要观察新的bug，并根据我们感知到的优先级对它们进行分类。很有可能不同的人会看到不同的错误优先级与我们非常不同，所以请让我们知道，如果你看到一个问题的具体门票。

检票和结账

如果有正面评价或其他原因，可以关闭门票。要了解如何复习，请参阅 审阅者的检查表 .

只有Sage发行经理会关闭门票。很可能，这不是您，您的trac帐户也没有必要的权限。如果您强烈认为应该关闭或删除记录单，请将记录单的状态更改为 需求回顾 并将里程碑更改为 sage-duplictate/invalid/wontfix . 你还应该对罚单进行评论，解释为什么要关闭它。如果另一个开发者同意，他就把罚单设为 正面评价 .

一个相关的问题是重新开票。你应该避免重开已经关闭的车票。相反，打开一个新记录单并在描述中提供到旧记录单的链接。

罚单作废原因

每张票一期 ：一张票必须只涵盖一个问题，而不应是一个不相关问题的详细清单。如果一张罚单包含多个问题，我们将无法关闭它，虽然某些补丁已应用于给定版本，但票证仍将处于不确定状态。

没有贴片炸弹 ：进入Sage的代码经过同行评审。如果您看到一个80000行代码包，它完全剥离了一个子系统并用其他东西替换它，您可以想象评审过程会有点乏味。这些巨大的补丁炸弹问题有几个原因，我们更喜欢小的，渐进的，易于审查和应用的变化。这并非总是可能的（例如强制重写），但仍然强烈建议您避免这种风格的开发，除非没有办法绕过它。

Sage特异性 ：Sage的哲学是，我们将所有（或接近它的）东西放在一个源tarball中，以使调试成为可能。你可以想象，如果你只用外部软件包替换Sage的10个组件，我们将不得不面对的组合爆炸。一旦你开始更换Sage的一些更重要的组件（如Pari、GAP、lisp、gmp），它就不再是属于我们跟踪系统的问题了。例如，如果您的发行版的Pari包有缺陷，请向他们提交一份bug报告。我们通常愿意也有能力解决这个问题，但不能保证我们会帮助你。看看Sage特有的公开票数，你希望能理解原因。

无支持讨论 ：trac安装不是用来跟踪使用Sage时的问题的系统。票应该是一个明显的错误，而不是“我试图做X，但我不能让它工作。我该怎么做？”这通常不是Sage中的bug，很可能 sage-support 可以帮你回答这个问题。如果你发现了一个错误，有人会开一张简洁明了的罚单。

解决方案必须是可实现的 ：门票必须是可获得的。很多时候，属于这一类的票通常与上面列出的其他规则相冲突。例如，“使Sage成为世界上最好的CAS”。没有一个标准来衡量这一点，这是高度主观的。