常见问题解答：为Sage贡献力量

我怎样才能开始为Sage做贡献？

第一步是使用Sage，并鼓励您的朋友使用Sage。如果您在此过程中发现错误或令人困惑的文档，请报告您的问题！

为Sage做贡献的两种流行方式是编写代码和创建文档或教程。下面描述了每个方向的一些步骤。

我想把代码贡献给Sage。我该如何开始？

请看一下 official development guide 为了塞奇。至少，该指南的第一章是任何Sage开发人员的必读内容。也要特别注意 GitHub guidelines 。您也可以加入 sage-devel 邮件列表或在 SageMath Zulip chat channel 。在您开始了解社区的同时，获取一份Sage源代码的副本，并熟悉 git 版本控制系统。

熟悉Sage开发过程的最好方法是从 the Sage repository on GitHub 并审查该问题中所载的拟议修改。如果你想要实现某件事，最好在 sage-devel 首先发送邮件列表，这样其他开发人员就有机会对您的想法/建议发表评论。他们对新思想也相当开放，就像所有数学家应该做的那样。

Sage的主要编程语言是 Python 。Sage的某些部分可能是用其他语言编写的，特别是执行大量数字处理的组件，但大多数本机功能都是使用Python实现的，包括“粘合代码”。Sage继承的一个好的方面是，工作代码被认为比仅仅是快速代码更有价值。快速代码很有价值，但干净、可读的代码很重要。在数学界，不准确的结果是不可接受的。正确先于优化。在接下来的文章中

  • D·克努斯。使用Go To语句的结构化编程。 ACM Journal Computing Surveys ，6(4)，1974。

Don Knuth观察到：“我们应该忘记小的效率，比如说97%的时间：过早的优化是一切邪恶的根源。”

如果你不懂Python，你应该开始学习这门语言。一个很好的起点是 Python Official Tutorial 和其他文件放在 Python standard documentation 。另一个值得一看的好地方是 Dive Into Python 这本书可能对测试驱动开发等特定主题非常有帮助。这本书 Building Skills in Python 由Steven F.Lott编写，适合任何已经熟悉编程的人。

如果您愿意，您可以尝试使用Sage学习Python。然而，知道什么是纯Python以及Sage何时在发挥它的“魔力”是很有帮助的。有许多东西可以在Python中运行，但在Sage中不能运行，反之亦然。此外，即使在语法相同的情况下，许多编程概念在以Python为中心的资源中比在以Sage为中心的资源中解释得更彻底；在后者中，数学通常是优先考虑的。

我不是程序员。有没有其他我能帮忙的方法？

是。与任何免费开源软件项目一样，您可以通过多种方式在Sage社区中提供帮助，而编程只是众多方式中的一种。

很多人喜欢写技术教程。这样做的乐趣之一是，你也在这个过程中学到了一些新的东西。同时，你将你的知识传递给初学者，这是一种在技术写作本身以外的领域有用的技能。关于技术写作的一个要点是，你与初学者交流一个技术主题，所以保持最少的技术术语。达雷尔·安德森写了一些 tips on technical writing ，我们强烈推荐。

对于平面设计师或有艺术创造力的人，您可以帮助改进Sage网站的设计。

如果你能用另一种(自然)语言说、读、写，你的贡献将在许多方面对整个Sage社区非常有价值。说你懂意大利语。然后你可以用意大利语写一个Sage教程，或者帮着把官方的Sage教程翻译成意大利语。

以上是一份非常简短的清单。你可以用很多很多的方式来帮助你。请随时发送电子邮件至 sage-devel 邮件列表，询问您可以帮助解决问题的可能方式，或提出项目想法。

我在哪里可以找到关于Python或Cython的资源？

以下是有关Python和Cython的资源的不完整列表。可以通过网络搜索找到更多资源。

General resources

Tutorials and books

Articles and HOWTOs

有什么编码约定需要我遵循吗？

您应该遵循标准的Python约定，如中所述 PEP 8 和 PEP 257 。还可以参考《Sage开发人员指南》，特别是 Conventions for Coding in Sage 。

几周前，我向GitHub Sage Repo提交了一个错误修复程序。你为什么不理睬我的分支机构？

我们并没有试图忽视您的分支机构。大多数在Sage上工作的人都是在他们的空闲时间这样做的。由于有数百个不同程度的开放式公关对整个Sage社区产生了不同程度的影响，从事公关工作的人需要优先考虑他们感兴趣的公关。有时你可能是唯一了解你的分支机构的人。在这种情况下，我们鼓励您格外小心，以使任何人都能尽可能轻松地查看它。以下是一些让您的分支机构更容易查看的小贴士：

  • 您是否清楚地描述了您的分支机构正在努力解决的问题？

  • 您是否提供了与您的补丁试图解决的问题相关的任何背景信息？这些信息包括指向在线资源和任何相关论文、书籍和参考资料的链接。

  • 您是否清楚地描述了您的分支机构如何解决正在考虑的问题？

  • 您是否清楚地描述了如何测试分支机构中的更改？

  • 您是否列出了您的分支机构所依赖的任何问题/PR？

  • 您的分支机构是否基于最近(最好是最新的)Sage测试版？

  • 你们的分支机构 follow relevant conventions 如《开发人员指南》中所述？

如果您的分支没有机会被合并到Sage源代码树中，我们不会忽略您的分支，而是简单地关闭相关PR，并解释为什么我们不能包括您的更改。

何时以及如何才能提醒Sage社区我所关心的分支机构？

我们鼓励您在提醒Sage社区您希望合并到Sage源码树中的分支/补丁时要格外小心。可能会有一个与你的补丁相关的即将到来的错误挤压冲刺或即将到来的Sage日研讨会。监控相关的Sage邮件列表，礼貌地回复任何相关的电子邮件线索，并清楚地解释为什么您的补丁是相关的。

我写了一些Sage代码，我想把它集成到Sage中。但是，在重命名我的文件后 a.sage 至 a.py ，我得到了语法错误。我必须用Python而不是Sage重写我的所有代码吗？

基本答案是肯定的，但重写是一个很重要的词，用来表达真正需要的东西。由于Sage主要遵循Python语法，因此可以做的工作很少。两个主要区别是对整数的处理(另请参阅 afterword 有关SAGE预备器的更多信息)，以及导入所需内容的必要性。

  • Handling of integers: 您需要注意以下更改：

    • 求幂的表示法：在Python中 ** 表示指数运算和 ^ 意思是“异或”。

    • 如果需要向用户返回一个整数，请编写 return Integer(1) 而不是 return 1 。在PYTHON中，1是PYTHON int ，以及 Integer(1) 是SAGE/GMP整数。此外, Integer 比起那些比 int 例如，他们知道素数和因式分解。

    • 您还应该注意到， 2 / 3 不再意味着 Integer(2) / Integer(3) 和回报 2/3 ，但更确切地说 int(2) / int(3) ，因此返回 0 由于整数除法，所以它对任何余数都不加标记。如果您正在处理 Integer 但你真的需要一个整数除法，你可以使用 Integer(2) // Integer(3) 。

  • Importing stuff: 第二个重大变化是必须进口你所需要的一切。更准确地说，每次使用某个Sage函数时，都需要在文件的开头导入它。例如，如果您希望 PolynomialRing ，您需要写下：

    from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing

    您可以使用 import_statements 要获取准确的必要行：：

    sage: import_statements(PolynomialRing)
from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing

    如果失败，您可以询问Sage在哪里可以找到 PolynomialRing 使用：：

    sage: PolynomialRing.__module__
'sage.rings.polynomial.polynomial_ring_constructor'

    这也对应于以下开始的路径 site-packages 当你向Sage索要 PolynomialRing 帮助。例如，如果调用 PolynomialRing? ，您将获得：

    Type:    function
[...]
File:    /path_to_sage_root/sage/local/lib/python3.7/site-packages/sage/rings/polynomial/polynomial_ring_constructor.py
[...]