(节选自"自由软件发布方法惯例")
原文
Software Release Practice HOWTO V3.4
中文译文:自由软件发布方法惯例 V3.0
【自由软件发布方法惯例 是很著名的文章了啦】
编写README文件
应该有一个名为README或者READ.ME的文件来说明整个源码的结构信息。古老的传统告诉我们,勇猛的探索者在解开您的压缩文件包后的第一件事情就是找出README文件来阅读。
README文件中最好应该包括如下信息:
整个项目的简介
项目的WWW站点所在的URL(如果有的话)
指出开发者编译整个项目所在的系统环境,并指出项目可能潜在的移植性问题
重要文件和子目录的结构信息
编译/安装步骤说明,或者指明这些信息所在的文件名(通常是INSTALL文件)
项目主持人和参与者的名单列表,或者指出这些信息所在的文件(通常是CREDITS文件)
最近关于本项目的一些进展情况和新闻,或者指出包含此信息的文件(通常是NEWS文件)
遵照标准文件命名规则
"勇猛的探索者"要想阅读README文件,他们就必须首先浏览解压后项目档案所在的根目录下的文件名。这些文件名本身就在向读者传达着许多信息。如果您遵照标准的命名规则就可以给那些探索者有价值得线索以便他们更好的理解您的意图。
这里列出了一些标准文件名称和他们的涵义。当然并不是所有项目发布时都必须包含所有这些文件。
README或READ.ME
整个项目的结构信息说明,第一个需要阅读的文件。
INSTALL
配置、编译和安装该项目的说明信息
CREDITS
本项目所有贡献者的列表
NEWS
本项目最近的一些新闻和进展状况
HISTORY
本项目的历史发展演变记录
COPYING
指出本项目采用的许可证条款(通常采用GNU GPL)
LICENSE
本项目的许可证条款文件
MANIFEST
本项目的所有文件列表
FAQ
关于本项目的纯文本格式的常见问题解答
TAGS
为Emacs或vi准备的tag标记文件
我们可以看出来,全部大写的文件名一般表示该文件是给人阅读的文档,而不是项目的一个组成部分。
编撰一个FAQ文件可以帮您很多忙。如果某个问题经常被其他人问起,就把这个问题列入FAQ文件?然后指导用户在向您发文或提交出错报告前首先阅读FAQ文件。一份好的FAQ文件可以给项目维护者减轻好几个数量级的负担。
另外在每次发布时都保留一个HISTORY文件和NEWS文件,并列明时间信息的做法是非常有好处的。在所有其他文件中,这两个文件可以让您在遇到一些专利侵权法律问题时有所准备(虽然这种情况至今还没有发生过,不过最好还是有备无患)。