常见问题解答:为Sage做贡献

我如何开始为Sage捐款?

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

对Sage贡献的两种常用方法是编写代码和创建文档或教程。每个方向的一些步骤如下所述。

我想为Sage贡献代码。如何开始?

看看 official development guide 为了Sage。至少,任何Sage开发人员都需要阅读该指南的第一章。还要特别注意 trac guidelines . 你也可以加入 sage-devel 邮件列表或在 #sage-devel IRC信道 freenode . 当你开始了解社区的时候,拿一份Sage源代码的副本,让自己熟悉 git 版本控制系统。

熟悉Sage开发过程的最佳方法是从 trac server 并检查该罚单中包含的建议更改。如果你想实现某件事,最好在 sage-devel 首先发送邮件列表,以便其他开发人员有机会对您的想法/建议发表评论。他们对新思想也相当开放,所有数学家都应该如此。

Sage的主要编程语言是 Python . Sage的某些部分可能是用其他语言编写的,尤其是那些处理大量数字运算的组件,但是大多数本机功能是使用Python完成的,包括“粘合代码”。Sage继承的Python的一个优点是工作代码被认为比快速代码更有价值。快速代码很有价值,但干净、可读的代码很重要。在数学界,不准确的结果是不可接受的。正确先于优化。在下面的论文中

  • D、 克努斯。带go-to语句的结构化编程。 计算机调查杂志 ,6(4),1974年。

donknuth观察到:“我们应该忘记小效率,比如97%的时间:过早优化是万恶之源。”

如果你不懂Python,你应该开始学习这种语言。一个好的开始是 Python Official Tutorial 以及其他文件 Python standard documentation . 另一个值得一看的地方是 Dive Into Python 作者markpilgrim,这可能对某些特定的主题非常有用,比如测试驱动开发。这本书 Building Skills in Python 作者:史蒂芬F.洛特适合任何已经习惯编程的人。

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

我可以使用SageMathCloud为Sage做贡献吗?

当然!如果要为Sage编写代码或更新官方文档,则需要在上安装Sage SageMathCloud . 有关安装详细信息,请参阅 the SageMathCloud FAQ .

我不是程序员。我还有别的办法可以帮你吗?

对。与任何免费的开源软件项目一样,在Sage社区中有许多方法可以帮助您,而编程只是众多贡献方法中的一种。

很多人喜欢写技术教程。这样做的乐趣之一就是你也能在这个过程中学到新东西。同时,你可以将你的知识传授给初学者,这项技能在技术写作之外的其他领域都很有用。关于技术写作的一个要点是你要向初学者传达一个技术主题,所以尽量减少技术术语。达雷尔·安德森写了一些 tips on technical writing ,我们强烈推荐。

对于平面设计师或艺术创意,你可以帮助改进设计的Sage网站。或者你可以用你的艺术眼光来审视SageMathCloud或Sage笔记本的界面,找出它们需要改进的地方。

如果你能用另一种(自然)语言说话、阅读和写作,你的贡献在很多方面对整个Sage群体都是非常有价值的。说你懂意大利语。然后你可以用意大利语写一篇Sage教程,或者帮助把Sage教程翻译成意大利语。

以上是一个很短的列表。有很多很多方法可以帮助你。请随时发送电子邮件至 sage-devel 邮件列表,询问可能的帮助方式,或建议一个项目的想法。

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

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

一般资源

教程和书籍

文章和操作指南

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

您应该遵循标准的Python约定,如中所述 PEP 8PEP 257 . 也可以参考Sage开发者指南,尤其是本章 Conventions for Coding in Sage .

几周前,我向trac服务器提交了一个bug修复程序。你为什么无视我的补丁?

我们不想忽视你的补丁。研究Sage的人都是在空闲时间这样做的。由于成百上千张公开的罚单对整个Sage社区产生了不同程度的影响,从事票务工作的人需要优先安排自己的时间,并为他们感兴趣的门票工作。有时候你可能是唯一了解你的补丁的人。在这种情况下,我们鼓励您格外小心,使任何人都能轻松地查看您的补丁。以下是一些让补丁易于查看的提示:

  • 您是否清楚地描述了您的补丁程序要解决的问题?

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

  • 您是否清楚地描述了您的补丁程序如何解决正在考虑的问题?

  • 您是否清楚地描述了如何测试补丁中的更改?

  • 你列出了你的补丁依赖的票吗?

  • 如果有多个修补程序,您是否清楚地说明了这些修补程序的应用顺序?

  • 你的贴片呢 follow relevant conventions 如开发人员指南中所述?

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

我什么时候,怎样才能提醒Sage社区我关心的补丁?

我们鼓励您特别注意如何提醒Sage社区您想要合并到Sage源代码树中的补丁。可能会有一个即将到来的bug-squashsprint或者一个即将到来的Sage-Days研讨会,与您的补丁程序相关。监控相关的Sage邮件列表,礼貌地回复任何相关的邮件,并清楚地解释为什么你的补丁是相关的。监视 #sage-devel IRC频道,注意策略性地安排提醒时间。

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

基本的答案是肯定的,但是重写是真正需要的一个词。由于Sage主要遵循Python语法,所以几乎没有什么工作要做。两个主要的区别是对整数的处理(另请参见 afterword 关于sage preparser的更多信息),以及进口所需物品的必要性。

  • 整数的处理: 您需要注意以下更改:

    • 指数表示法:在Python中 ** 表示指数和 ^ 意思是“异或”。

    • 如果需要向用户返回一个整数,请写 return Integer(1) 而不是 return 1 . 在Python中,1是Python intInteger(1) 整数为Gmp/a。此外, Integerint 例如,他们知道素数和因式分解。

    • 你也应该注意到 2 / 3 不再意味着 Integer(2) / Integer(3) 回报 2/3 ,但是 int(2) / int(3) ,因此返回 0 因为整数除法在这里除掉任何余数。如果你正在处理 Integer 但是你真的需要一个整数除法 Integer(2) // Integer(3) .

  • 导入资料: 第二大变化是必须进口你需要的一切。更确切地说,每次使用Sage函数时,都需要在文件的开头导入它。例如,如果你想 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:    /home/florent/src/Sage/sage/local/lib/python2.6/site-packages/sage/rings/polynomial/polynomial_ring_constructor.py
    [...]