软件发行惯例HOWTO

1. 介绍
1.1 本文档为什么存在?
1.2 本文档的新版本
2. 好的工程命名惯例和存档(archive)命名惯例
2.1 把GNU风格的名字用于词干（stem）和major.minor.patch编码。
2.2 但在适当的时候尊重原有的习惯（local conventions）
2.3 尽力去选择一个独一无二并且易于输入的名称前缀
3. 好的许可证和版权惯例：理论
3.1 开放源代码和版权
3.2 开放源代码应该施加什么限制（qualifies）
4. 好的许可证和版权惯例：实践
4.1 使你自己或者自由软件基金会（FSF）成为版权的所有者
4.2 使用符合开放源代码定义的许可证
4.3 只要可能避免，就不要编写你自己的许可证。
5. 好的开发惯例
5.1 用纯标准C（ANSI C）或者可移植的脚本语言编码
5.2 服从好的C可移植惯例
5.3 使用autoconf/automake/autoheader
5.4 在发布你的代码之前进行完整性检查（Sanity-check）
6. 好的发布创建惯例
6.1 确保tar包总是打开到一个单独的新目录中
6.2 含有一个README
6.3 尊重并服从标准的文件命名惯例
6.4 提供RPMs
7. 好的交流惯例
7.1 在c.o.l.a中进行通告
7.2 在相关主题的新闻组中进行通告
7.3 拥有一个网站
7.4 为工程提供邮件列表
7.5 发布到主存档中
8. 好的工程管理惯例

 

1. 介绍
1.1 本文档为什么存在?
对于开发源代码，有许多有助于他人移植、使用和合作开发的好的实践传统。这些习惯中的一部分是Unix世界的传统并且出现在Linux之前；其他的则在最近因为特定的新工具和技术，例如互联网（World Wide Web），的出现而发展起来。
本文档将帮助你学习好的惯例。它是按照主题来组织的，每个主题包含一系列检查（checklist）的条目。把这些条目看作你发布之前需要检查的条目吧。
1.2 本文档的新版本
本文档将按月发送到新闻组comp.os.linux.answers中。本文档在许多Linux FTP站，包括metalab.unc.edu，中的 pub/Linux/docs/HOWTO上进行了归档。
你还可以通过下面的互联网URL访问本HOWTO的最新版本。 http://metalab.unc.edu/LD
P/HOWTO/Software-Release-Practice.html.
请大方地把任何关于本HOWTO的问题或者建议用Email发送给Eric S. Raymond， esr@snark.thyrsus.com。
--------------------------------------------------------------------------------
2. 好的工程命名惯例和存档(archive)命名惯例
随着对诸如Metalab、PSA站点和CPAN存档维护的工作量的增加，就越来越趋向于用程序来处理一部分或者所有的工作（而不是完全有人来完成）。
这就使得工程和存档文件的名称符合计算机程序可以解析和理解的常见模式变得越来越重要了。
2.1 把GNU风格的名字用于词干（stem）和major.minor.patch编码。
如果你的归档文件都使用类似GNU的名称 -- 全部由小写字母和数字组成的词干前缀，而后是横线、而后是版本号、扩展名和其他后缀，那就对每个人都有帮助。
让我们假定你有一个称为`foobar'的工程是第1版，第2次发行，第3级。如果它只有一个归档部分（大概是源代码），这就它应有的名字
foobar-1.2.3.tar.gz
源代码存档
foobar.lsm
LSM文件（假定你要提交到Metalab中）。
请不要使用这些名字：
foobar123.tar.gz
对许多程序来说，它看起来像个名为`foobar123'的工程而没有版本号的存档。
foobar1.2.3.tar.gz
对许多程序来说，它看起来像个名为`foobar1'而版本号为2.3的工程。
foobar-v1.2.3.tar.gz
许多程序认为该工程称为`foobar-v1'。
foo_bar-1.2.3.tar.gz
对于人来说，下划线难于发音、输入和记忆
FooBar-1.2.3.tar.gz
除非你原意使你看上去像一个小市民（marketing weenie）。对于人来说，它同样难于发音、输入和记忆。
如果你必须区分源代码和二进制存档，或者区分不同种类的库，或者在文件名中表达某种创建选项，请把它们作为文件扩展名而放在版本号之后。就是，这样作：
foobar-1.2.3.src.tar.gz
源代码
foobar-1.2.3.bin.tar.gz
二进制码，没有给出类型
foobar-1.2.3.bin.ELF.tar.gz
ELF二进制码
foobar-1.2.3.bin.ELF.static.tar.gz
静态连接的ELF二进制码
foobar-1.2.3.bin.SPARC.tar.gz
SPARC二进制码
请不要使用诸如`foobar-ELF-1.2.3.tar.gz'之类的名字，这是因为程序在把类型中缀（比如`-ELF'）从词干中区分出来的时候会遇到困难。
一个好的通用名称的形式按照顺序含有下列部分：
项目前缀
横线
版本号
点
"src"或者"bin"（可选的）
点或者横线（点更好些）
二进制类型和选项（可选的）
归档和压缩扩展名
2.2 但在适当的时候尊重原有的习惯（local conventions）
某些工程和社团已经为名字和版本号定义了好的惯例，它不必与上述建议相兼容。例如，Apache模块通常按照诸如mod_foo的形式命名，以及它们自己的版本号和与之工作 Apache的版本号。类似地，Perl模块含有可以被看作浮点数的版本号（例如，你可能看到1.303而不是1.3.3），而且对模块Foo::Bar的1.303版的发布通常名为Foo-Bar-1.303.tar.gz。
寻找并尊重特定社团和开发者的习惯；对于一般用途，就服从上述的指引。
2.3 尽力去选择一个独一无二并且易于输入的名称前缀
词干前缀对于所有工程中的文件都应该是共有的，并且它应该易于诵读、输入和记忆。所以请不要使用下划线。并且在没有极好的理由的时候不要用大写或者部分使用大写字母 -- 它会干扰人类眼球的搜索顺序而且看起来有点象小市民在耍小聪明。
在两个不同的工程使用相同的词干名的时候，将造成混淆。所以在你首次发行之前尽力对冲突进行检查。一个进行检查的好地方是 index file of Metalab。


3. 好的许可证和版权惯例：理论
你所选择的许可证定义了你希望在你和你的协作开发者以及用户之间设定的社会契约。你为软件设定的版权将主要起到对你为软件以及从软件中派生出的工作设置许可证的法律声明的作用。
3.1 开放源代码和版权
任何不属于公众（public domain）的东西都是有可能多于一个的版权的。按照伯尔尼公约（自从1978年以来成为美国的法律），版权并不必须显式地声明。就是说，即使没有给出版权声明，一部作品的作者仍然持有版权。
究竟谁是作者，是十分复杂的，尤其对于经过了许多人的工作的软件。这就是为什么许可证是重要的。通过为能够使用那些材料而设定条款，它们可以对用户进行授权以便在版权所有者独断专行时保护用户。
在私有软件中，许可证条款被设计成保护版权的。它们是一种在确保拥有者（版权的所有者）保留大部分法律权力的同时，把少数权力授予使用者的方式。版权所有者是非常重要的，而且许可证的逻辑是如此的严密以至于许可证条款在技术上的精确通常并不重要了。
在开放源代码软件中，情况通常恰恰相反；版权的存在保护了许可证。版权所有者的唯一权力就是保持并强制实行许可证。否则，只保留少数权力并且大部分选择交给了用户。特别地，版权所有者不能修改你已经拥有的副本的条款。因此，开放源代码软件的版权所有者几乎是不相关的 -- 但许可证条款是十分重要的。
项目的版权所有者一般是项目的当前领导者或者组织的发起者。把项目转手给新的领导者通常需要为版权所有者的改变而进行标注（signaled）。然而，这并不是一个艰难而牢固的规则；许多开发源代码项目都有多个版权所有者，而且还没有发生过这种纪录导致法律问题的先例。
有些软件项目选择把版权赋予自由软件基金会，在理论上，这种做法对开放资源的保护具有重要的意义，在法律上也是可行的。
3.2 开放源代码应该施加什么限制（qualifies）
关于许可的目的，我们可以把它们区分成几种许可证可以转让的权力。复制与再发布的权力， 使用的权力，为个人使用而修改的权力，对修改后的版本进行再发布的权力。许可证可以对任何这些权利进行限制或者附加条件。
开放源代码宗旨是大量关于如何使软件“开放源代码”或者（按照过去的术语）“自由”的思考的结果。它对许可证的限制为：
必须授予不受限制的复制的权力。
必须授予不受限制的使用的权力。
必须授予不受限制的为个人使用而修改的权力。
该指导方针禁止对再发布修改后的二进制码施加限制；它满足了那些不希望带有任何麻烦地发放工作代码的软件发布者的需要。它允许作者要求修改的源代码以本来的代码再加上补丁的形式再发布，从而确保作者的意图以及其他人所作的任何修改的“审核纪录”。
开放源代码定义（OSD）是‘OSI Certified Open Source’认证标志的法定定义，而且是人们曾经提出的 “自由软件”的良好定义。所有的标准许可证（MIT、BSD、Artistic以及GPL/LGPL）都满足它（虽然有些，比如说GPL，含有其他限制，你应该在选择它之前理解它）。
值得注意的是只允许非商业用途的许可证，即使是用“GPL”或其他标准许可证进行了装饰，也不 具备开放源代码许可证的资格。它们歧视了特定的职业、个人和群体。它们使得CD-ROM的发放者和其他试图商业地散发开放源代码软件的人的生活变得太复杂了。
----------------------------------------------------------------------------
4. 好的许可证和版权惯例：实践
这里是如何把理论变为实践：
4.1 使你自己或者自由软件基金会（FSF）成为版权的所有者
在某些情况下，如果你有一个以律师支持你的发起组织，你可能希望把版权授予那个组织。
4.2 使用符合开放源代码定义的许可证
开放源代码定义是为许可证设定的黄金公共标准。OSD本身并不是许可证；相反，为了确认一个开发源代码许可证，OSD定义了许可证必须确保的权力的最小集合。OSD和支持资料，可以在网站开放源代码宗旨上找到。
4.3 只要可能避免，就不要编写你自己的许可证。
众所周知的，服从OSD的许可证拥有良好定义的解释性惯例。开发者（以及他们所关心的，用户）知道它意味着什么，而且对于其风险和他们涉及到的交易（tradeoffs）有合理的感受。因此，只要可能，就使用一个从OSI获得的标准许可证。
如果你必须编写你自己的许可证，请确认它得到了OSI的认证。这将避免大量的争论和花费。除非你已经考虑过了，你不会理解一个许可证的缺陷会导致多大的威胁；由于许可证被看作是近于神圣的关于开放源代码社团的核心价值观的协约，人们因而变得充满热情。
进一步，如果你的许可证已经在法庭上经过了检验，就证实了已经建立的解释性惯例的存在的重要性。在写作本文时（1999的近期），还没有出现支持或反对任何开放源代码许可证的法律案件。然而，它是一个法庭应该根据预期的意图（expectations）以及社团发起者的实践来解释的许可证和合同的法律文献（至少在美国，以及其他诸如英格兰和不列颠联邦的其它地方的，普通法律的国家是这样）。
------------------------------------------------------------------------------------
5. 好的开发惯例
这些惯例的大部分都与确保移植性，不仅仅在Linux界还包括其他Unix系统，有关。可以移植到其他Unix上不只是专业主义的可敬形式（a worthy form of professionalism），而且易于理解（hackerly politeness），它还是对未来Linux本身的变化的有价值的保险。
最后，其他人将试图在非Linux系统中创建你的代码；可移植性将最大限度地减少你将获得的恼人的，令人困惑的电子邮件消息。
5.1 用纯标准C（ANSI C）或者可移植的脚本语言编码
为了移植性和稳定性，你应该用纯标准C（ANSI C）或可移植的脚本语言编程，脚本语言因为只有一种跨平台实现而被确保是可以移植的。
具备这种资格的脚本语言包括Python、Perl、Tcl和Emacs Lisp。普通的老式shell 没有这种资格；它有太多的带有微妙特性的不同实现，而且shell环境受到诸如shell别名之类的用户定制干扰。
Java给出了成为可移植语言的承诺，但对Linux可用的实现仍然凌乱而不能与Linux很好地集成。虽然Java随着它的成熟变得更加流行，Java仍然是一种可能付出代价的选择（bleeding-edge choice），
5.2 服从好的C可移植惯例
如果你用C编程，不要有任何犹豫地使用所有标准（ANSI）特征 -- 包括函数原型，它将帮助你发现跨模块的不一致性。老式的K&R编译器已经成为历史。
另一方面，不要假定任何GCC特有的功能，比如说`-pipe'选项或嵌套函数，是可用的。
它将在别人把它移植到非Linux、非GCC的系统的时候苏醒并咬你一口。
5.3 使用autoconf/automake/autoheader
如果你用C编程，使用autoconf/automake/autoheader来处理移植性问题，完成系统配置探查，以及制作你的makefiles。今天人们从源代码进行创建时希望能够输入"configure; make"并且获得一个清晰的创建 -- 而且正是这样。
5.4 在发布你的代码之前进行完整性检查（Sanity-check）
如果你用C编程，使用-Wall进行测试编译并且至少在每次发布之前清除一次错误。它会找到今人数目的错误。为了完整，还要用-pedantic选项进行编译。
如果你用Perl编程，就用perl -c（如果可以，可能是-T）来检查你的代码。坚持使用p
6. 好的发布创建惯例
这些惯例描述了在有人下载你的发布包的时候，它们看起来是怎样的，如何检索以及如何解包。
6.1 确保tar包总是打开到一个单独的新目录中
一个困扰大部分新的开发者的错误是创建的tar包将把它的文件和目录解包到当前目录中，这潜在地与已经位于那里的文件发生冲突。 决不要这样做！
相反，确认你的存档文件在工程之后都含有一个通用目录的部分名称，以便它们能够被解包到一个单独的在当前目录下的一个顶层目录中。
假定你的发布目录名为`foobar'，而且SRC包含了你所发布文件的列表，有个makefile诀窍可以完成这项任务。它需要GNU tar 1.13
VERS=1.0
foobar-$(VERS).tar.gz:
        tar --name-prefix='foobar-$(VERS)/' -czf foobar-$(VERS).tar.gz $(SRC
)
如果你的tar是老式的，就向下面那样作：
foobar-$(VERS).tar.gz:
        @ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST
        @(cd ..; ln -s foobar foobar-$(VERS))
        (cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar/MANIFEST`
)
        @(cd ..; rm foobar-$(VERS))
6.2 含有一个README
含有一个名为README或者READ.ME的文件，它是你的源代码发布的路标。按照过去的习惯，该文件是勇敢的探索者在解包源代码之后阅读的第一个文件。
包含在README中的有用信息包括：
工程的简要描述。
（如果有的话，）一个指向工程网站的指针
说明开发者的创建环境和潜在的移植性问题。
对重要文件和子目录进行路标式的说明。
关于创建/安装的指南，或者是指向包含这类信息某些文件（通常是INSTALL）的指针。

关于维护者/致谢者的列表，或者是指向包含这类信息的某些文件（通常是CREDITS）的指针。
关于工程近期的新闻，或者是指向包含这类信息的某些文件（通常是NEWS）的指针。
6.3 尊重并服从标准的文件命名惯例
甚至在阅读README之前，你的勇敢的探索者就已经察看了你的解包的发布中顶层目录中的文件名。这些名字本身就传达了信息。通过服从某种标准命名惯例，你可以为探索者提供下一步应该阅读什么的有价值的线索。
这里是一些标准顶层文件名以及它们的含义。不是每个发布都需要所有这些文件。
README或者READ.ME
路标文件，首先阅读
INSTALL
配置、创建与安装指南
CREDITS
工程贡献者的列表
NEWS
近期的工程新闻
HISTORY
工程的历史
COPYING
工程的许可证条款（GNU惯例）
LICENSE
工程的许可证条款
MANIFEST
发布中文件的列表
FAQ
为工程提供的普通文本的常见问题解答（FAQ）文档
TAGS
为使用Emacs或者vi而生成的tag文件
总的习惯是，全部由大写字母构成的文件名是人类可读的关于包的元信息（metainformation），而不是创建中的成分。
6.4 提供RPMs
可安装的二进制包的事实标准（de-facto standard）格式由Red Hat包管理器，RPM所使用。它出现在大部分流行的Linux发行版中，而且所有其它Linux发行版都有效地支持它（除了Debian和Slackware；而且Debian也可以从RPM中安装）。
因此，在你的工程站点提供源代码tar包的同时，提供可以安装的RPM包是个好主意。对你来说，把你的源代码tar包和从你的Makefile中制作RPM的产物一同包含在RPM spec 文件中也是个好主意。spec文件应该使用扩展名`.spec'；这就是rpm -t选项如何在tar包中寻找它的方法。
对于特殊风格的地方，通过分析Makefile或者version.h，使用自动添加正确的版本号的 shell脚本来生成你的spec文件。
--------------------------------------------------------------------------------
erl -w和'use strict'。（参见Perl文档的讨论。）

--
7. 好的交流惯例
如果除了你自己之外没有人知道你的软件的存在，它就不会使世界变得更好。还有，使发展中的工程在Internet上可见将帮助你找到你的用户和协作开发者。下面是这样做的标准方式。
7.1 在c.o.l.a中进行通告
把新的发布在 comp.os.linux.announce上进行公告。除了它本身能够被广泛地阅读之外，该组织是一个类似与 Freshmeat的，基于网络的what's-new的站点主要的支持者。
7.2 在相关主题的新闻组中进行通告
寻找与你的应用程序直接相关的USENET主题阻，并且也要在它上面通告。只能在代码功能相关的地方公布。
（例如）如果你要发布用Perl编写的，查询IMAP服务器的程序，你就应该在comp.mail.imap 上进行公布。但是除非程序还是关于Perl临界技术（cutting-edge Perl techniques）的一个有益范例，你可能不应该在comp.lang.perl上公布。
你的声明应该包含工程网站的URL。
7.3 拥有一个网站
如果你打算为你的工程创建一个实质性的用户和开发者社团，它就应该有一个网站。应该在网站上出现的标准的东西有：
工程的宪章（它为什么存在，谁是听众，等等）。
关于工程源代码下载的连接。
如何加入工程邮件列表的指南。
常见问题解答（Frequently Asked Questions）列表。
HTML版的工程文档
到相关的以及/或者竞争工程的连接。
有些站点甚至还提供对主源代码树进行匿名访问的URL。
7.4 为工程提供邮件列表
为工程合作者提供私有的，可以通讯和交换patch的开发列表是一种标准的做法。你可能还要为需要及时获得工程进展通知的人们提供一个声明列表。
7.5 发布到主存档中
在最近的几年中， Metalab archive已经成为最重要的 Linux软件交流的地方。
其它的重要地点有：
Python Software Activity站点（为使用Python编写的软件而提供的）。
CPAN，完整Perl存档网，（为使用Perl编写的软件而提供的）。
--------------------------------------------------------------------------------

8. 好的工程管理惯例
在所有的参与者都是志愿者时，有效地管理一个工程带来了一些独特的挑战。这个题目太大了以至于不能被包含在HOWTO中。幸运地，已经有了一些有用的白页（white papers）可以帮助你理解主要的问题。
关于基本开发组织和早发布常发布的‘集市模式’的讨论，参见 大教堂与集市（The Cathedral and the Bazaar）。
关于动机心理、社团习俗和冲突的解决的讨论，参见 开拓智域（Homesteading the Noosphere）。
关于经济学和适当的商业模式的讨论，参见 The Magic Cauldron.
这些文章并不是开放源代码开发的最终声明。但它们是已经写出的第一个系列，并且将被代替。
--------------------------------------------------------------------------------