Question

我有一个相当简单的开源Java项目。这个过程对我来说是新的，我习惯只为自己编写程序。在Java中发布开源项目时需要注意哪些好的做法？

以下是我能想到的一些事情，你能否提出其他建议？

版本控制存储库（您用什么来解释相关标签/分支？外部自述文件？）
在代码中包含适当的open-source license
包括预先打包的可执行JAR文件，包括文件名中的版本号
解释构建/运行软件所需的外部依赖关系的某种README文件（有什么文件名和放在哪里的常见约定？）
项目的网页，包含源代码和/或可执行文件中的链接，以防有人首先获取源代码或可执行文件（而不是通过相关网页）

Answer 1

你应该做的一件事（因为它是Java）是为你的代码生成Javadocs。这意味着使用Javadoc表示法注释类和方法，以便于其他人阅读。

Answer 2

您还可以使用Maven来发布代码。有了它，可以很容易地为您的项目创建一个站点，指定依赖项，优化发布......例如，Apache的Commons项目使用Maven。

Answer 3

基本上，您希望您的项目能够“开箱即用”。当人们为任务选择正确的开源项目时，他们会下载一堆项目，表示他们支持该任务，并使用最好的项目。如果一个项目需要大量的工作来设置（例如从20个不同的站点下载20个JAR依赖项），大多数人只会尝试它作为最后的手段或者只是忽略它。

存储库：您可以尝试一些较新的存储库引擎 - 例如Mercurial或Git。它们简化了开发并简化了分支机构的合并。但重要的是，选择IDE本机支持的引擎。

依赖关系：您应该使用自述文件来声明依赖关系，但这还不够，使用Maven来管理依赖关系，在这种情况下，您只需要需要包含pom.xml文件，或者包含您在发行版中依赖的JAR。在第二种情况下，将依赖关系划分为mandatory，optional，compiletime和test。可选依赖项的一个例子是Hibernate的字节码生成工具。

网站：Maven可能create a site与您的软件的特定版本相关联（但从未使用过）。

文档 - JavaDoc ：记录所有内容，并尝试实施确保高质量javadoc的策略：

 /**
  * Sets the cost
  * @param decimal cost 
  */
 public void setCost(BigDecimal decimal){

没用。更好的是：

 /**
  * Sets the cost, cost is in currency setted by #setCurrency. 
  * @param decimal cost, precision shoule be at least three places
  */
 public void setCost(BigDecimal decimal){

文档：Javadoc还不够。给出一些起点 - 一个教程是可取的（我并不是指带有许多eclipse对话框截图的教程;））。示例代码也可以，或者至少在某处写 - “读取EntryPoint类的javadoc是开始使用此库的好方法”。如果您只有javadocs，那么正在考虑使用您的图书馆的人将会看到所有分支和包裹的列表，并且不知道从哪里开始。

错误跟踪软件：您不会再记得一次三个错误（并且会忘记一些事情） - 它还可以帮助您管理任务和新想要的功能。您可以尝试：

FogBugz - 很好，但要花钱。（最多两名开发人员免费）。
Bugzilla - 不错，受欢迎且免费

项目管理软件：这将帮助您计算发布日期，在开发人员之间拆分任务等。

dotProject - 免费且好的。
FogBugz - 再次效果很好。

尝试通过Joel test

构建流程：使构建成为一键式处理。例如，一个增加版本号的ant脚本，启动maven构建，部署站点等等。值得努力！

论坛：一个好主意，将有助于支持。

Wiki ：在许多（甚至是非常发达的）项目中，这样的wiki是空的，这很糟糕（因为它让人们想到'如果没有人在这个wiki中写，这怎么可能是很棒的软件' ）。

Answer 4

计划开发某种类型的网站。如果您的代码涉及网络软件，那么如果您将其用作网站的一部分，那么人们会非常惊叹。
开发人员喜欢好文档和大量样本。我见过的项目有很多强大的代码，但0％的文档很难实现。
有一个wiki设置让人们写出想法和食谱是一个明确的优点。（我推荐mediawiki）。
发布想法，讨论主题，即社区论坛的论坛也很好。
设置邮件列表并鼓励人们加入。
发布您的邮件列表，维基站点的真实更新，以及主站点上的新闻，以显示您正在处理的事情。鼓励参与。让自己可用。这一切都会产生一种感觉，即你在切入时感兴趣，并且你可以接受别人的输入。

Answer 5

我建议使用MAVEN作为管理构建/运行所需的外部依赖项的工具

你可以同时使用Vulcan或类似的连续混合，因此众所周知当前版本是否正常工作。

Answer 6

我知道已经提到了Maven，但我认为比使用Maven更重要的是将工件发布到Maven存储库，以便使用Maven的项目可以使用它们。然后，您的项目页面可以提供指向仓库的直接链接，因此它也可以作为可下载的存储空间。

另外：类似地，制作罐子OSGi捆绑 - 这只是添加一些Manifest条目，没有什么非常复杂 - 是另一件好事。

这些都可以帮助其他人更轻松地向您的软件包添加依赖项（如果适用）并且可以帮助其采用。

还有一些事情需要考虑：

明智的版本号方案（针对不兼容的更改的主要版本凹凸;针对具有向后兼容性的添加的次要版本;或类似的东西）
保持良好的发行说明
使用错误跟踪系统，如果你可以轻松使用它（Codehaus，dev.java.net，SourceForce等都提供此功能）
文档的简单项目Wiki
供讨论的邮件列表

Answer 7

从签到评论生成ChangeLog。单独创建一个发行说明，说明您在每个版本中修复/添加的内容。

Java发布工程的良好实践

7 个答案: