Eclipse开源政策系列 – 09 – 版本评审

请查阅Eclipse开发进程中的 “6.3.3 版本评审” 和 6.3 评审”

版本评审的目的是:总结该次发布的版本的成就，确认有遵循知识产权政策并且所有的许可都有被接受，强调出遗留的结构和质量上的问题，确认该项目将会依据Eclipse的原则和目的继续运作下去；

概述

请查阅 版本周期, 其中包含一个对版本评审过程的不错的简要概述；

可以从Eclipse 开发进程 中获取更多有用的文档

• 关于版本评审
• 版本评审的指导方针

服务发布版是不需要进行版本评审的

值得注意的是，服务发布版或者仅仅是进行bug修复的版本是不需要进行版本评审的。如果你的发布的版本不包含新特性、新API、或功能上的重大变化，那么你就可以在不进行社区评审的情况下发布它。但是你仍然需要在PMI中创建版本记录以通知你的社区；服务发布版的发布将通过版本号的第三位数字的增长进行标识（e.g. 2.3.2）；

同样值得注意的是，进行服务版本发布的时候是不需要提交知识产权日志供知识产权团队进行评审的。我们需要确保项目在任何一个时刻都有对所有相关的知识产权（例如CQ和贡献记录）进行一定的覆盖

知识产权

在你打算进行版本评审之前，所有的贡献调查表（CQ）都必须经过Eclispe法律小组的批准。我们应该把评审安排在法律小组完成他们的工作之后进行。如果你正在等待CQ，那么你可以在知识产权团队工作队列中查看你的CQ正处于哪个阶段，以及被安排到什么时候进行评审；

当你确认所有相关的的贡献调查都被批准后，你必须在安排的评审日期的前一周之前完成以下几条：

1. 得到项目管理委员会（PMC）的批准(可在完成知识产权批准之前、之后、或与其并行处理);

2. 完成知识产权日志的批准，这是任何一个版本评审都不可或缺的必要的条件!;

3. 评审的相关文档.

知识产权日志的批准

由于知识产权日志文件的评审是必不可少的，并且所花费的时间也是不确定的（花费的时间取决于知识产权小组的工作队列的长短），所以相关项目必须在评审日期确定之前获取到通过评审的知识产权日志；在你把知识产权日志提交到Eclispe法务进行审批后，版本评审将会被添加到进度表中，并会被打上一个标识“等待知识产权日志”的符号；在Eclipse管理组织（EMO）发出知识产权日志审批通过的通知后，这个符号会被替换成版本评审的日期；

请使用自动化的知识产权日志工具进行知识产权的更新和提交，比如 知识产权日志生成器（提交知识产权日志到Eclipse法务这一章节讲述了如何提交知识产权日志）；将http://www.eclipse.org/projects/ip_log.php?projectid=project ID中的projectID替换成你的项目ID后，就是为你的项目使用该工具的URL 。

在提交你的知识产权日志之前，我们建议你检查一下你的项目的下载目录的相关内容，确保必需的贡献调查表都有包含在里面；项目下载检查这款工具可以帮助你进行上述的检查；

当你在等待知识产权日志的评审时，我们建议你去获取项目管理委员会对此次版本评审的批准，并且开始进行一些文档相关的工作；

项目管理委员会（PMC）的批准

请转发一封邮件，表明你的版本评审已经得到了项目管理委员会的批准，并且已经准备了相应的评审文档。最简单的方式是通过项目管理委员会的邮件列表(需要订阅)获取批准，并把回复的邮件转发给Eclipse管理组织；

注意，在你的知识产权日志被知识产权小组审批通过之前，你不必一直等待，你可以在知识产权日志从知识产权日志批准流程中分离出来之前，向项目管理委员会提出评审文档的审批申请；

项目计划

你的 项目计划 必须是最新的，且是公开的.

评审文档

评审文档所需要的内容在下面有详细介绍，提供评审文档的首选方式是直接将其记录在与其关联的版本的项目元数据中；

可选的格式

在过去，通过PDF格式描绘的展示文档(PPT或ODP)是评审文档的首选格式（我们经常组织实际的评审电话，在这种情况下，上述的展示格式是非常合适的）。其他的公开格式，包括HTML、维基页面、或者用PDF描绘的文档文件，都是可以被接受的；

请通过邮件将你的文档提交给Eclipse管理组织。并以链接或者附件的形式包含你的评审文档；

许多人低估了创建这些文档需要花费的时间和精力，所以一定要为这项任务提供足够的时间。“官方”给出的文档的期限是在评审周期计划开始的前一周之前；然而，这些文档在被公布之前是需要给Eclipse管理组织进行评审的。如果你在到期日之前一直等着提交你的初稿，但是eclipse管理组织的要求变了，那么你就很有可能错过了你的截止日期，你的评审就会被延期。

检查清单

这看起来挺吓人的，其实是纸老虎，所以勇敢一点.

● 最新的项目网站:

○ 标明正确的项目孵化状态(如果有适用的)

○ 适当的做一些有意义的事情，以促进社区的发展

○ 项目需要有一个贡献指南

● 最新的项目元数据

○ 版本元数据是正确的且是最新的

○ 包含有认真填写的项目介绍(请查阅 项目介绍要包含什么，为什么要创建项目介绍).

● 项目计划是最新的，并且是标准格式的Project plan is up-to-date and in the 标准格式的

● 代码和项目的构建都是井然有序的:

○ 所有的项目代码都可以通过org的VCS进行访问

○ 所有的项目源码库都有包含一个捐献文件

○ 至少有一个可访问的里程碑构建

○ 构建的项目托管在eclipse.org 上

○ 已存档的构建托管在eclipse.org 上

○ 命名规范如下:

功能块和包命名为g. org.eclipse.<subproject>.<component>[.*]

○ 版本编号规则如下

○ 功能块的menifest文件中，有在Eclipse <project name>下包含一个“Bundle-Vendo”的条目；

○ 所有的功能块包含有一个html的说明文件(该要求来源于基于Eclipse的内容的合法文档指南 )；

○ 功能特性的名称和描述不要有遗漏、要正确的拼写、要使用正确的语法、并且包含有对预期读者有实际帮助的内容；

○ (如果处于孵化阶段)需要在发布物上标明

○ 为发布物提供明确定义的保留策略(e.g. p2 repositories)

● 和评审安全相关的bug可能会影响你的项目，在这种情况下你需要准备缓和策略:

○ 披露对应的安全性问题

○ 不透露对应的安全性问题(不向公众披露对应的问题)

● 所有的下载都包含必要的合法性文档(其中包含一个项目许可的副本)，该要求来源于基于Eclipse的内容的合法文档指南 .

● 知识产权日志文件准备就绪

○ 为项目首次贡献提供一个评审通过的贡献调查表;

○ 为所有在项目代码中使用到的第三方库提供一个评审通过的贡献调查表（无论这些库用没有被该项目所发布）

使用 项目下载评审 工具确认必要的共享调查表有被放在对应的位置；

● 发布渠道是畅通的(比如这个项目的下载链接——链接)

○ 老版本有被移到归档服务器中去吗？

○ 老版本的“每晚的整合构建”有被移除掉吗？

● 在评审周期开始的前一周之前需要提交知识产权日志供Eclipse知识产权小组进行检查

○ 检查知识产权日志中包含的相关贡献物

○ 下载中是否包含一些需要提供贡献调查表的第三方库

● 已经获取项目管理委员会的批准 (一般会通过项目的邮件列表进行获取)

● 评审文档 (详细介绍如下)

○ 正确的版权申明 和 Eclipse 公共许可申明;

○ 项目计划的链接格式正确(具体格式参照开发项目计划标准格式), 提供知识产权日志

○ 逻辑信息: 日期, 通信渠道 (比如项目邮件列表)

● 在评审周期开始的前一周之前将项目管理委员会评审过的评审文档提交到Eclipse管理组织；

如果你有任何疑问，请咨询 Eclipse管理组织.

注意，处理知识产权日志和评审文档所需的时间会因当时的系统负载而有所不同，所以我们会特别地做一些要求，比如说，.提前一个月提交知识产权日志，以便于项目能够加入到一年一次的集体发布活动中去。

哪些是必要条件

在主要版本发布之前进行版本评审，是为了证明该版本的主要目标已经达成，并且所有的知识产权问题都有被解决；.对于那些典型的“六周里程碑”Eclipse项目，大概需在最后一个“六周”开始时，花上一到两周的时间进行版本评审，也就是说在版本评审计划上线之前的四到五周开始进行版本评审。

版本评审包含哪些内容?

版本评审是为了确保 Eclipse质量而对项目、过程、版本和知识产权问题、的最后检查，其中对针对产品特点的知识产权问题的检查尤为重要；

版本评审是一个极具综合性的一个过程。我们知道为评审收集材料和准备文档需要付出很大的精力，但是我们相信这件事情给我们带来的自我反省对于项目是很有用的，这件事情所造就的结果对社区也是很有帮助的。

版本评审所要包含的项的列表如下，如果（版本评审）提供的文档是幻灯片形式的(这里有一个模板链接)，那么平均每项大概需要一页到两页幻灯片；如果使用的是文本文档（用一些开放格式，比如HTML），那么每一项需要包含一到两个段落或者包含少量的段落编号；.

在整个过程中要注意“概述”这一词的使用，对于这些项中需要描述多少内容这个问题，一定要慎重判断，然后再做决定。

产品特点

总结本次发布的主要特性以及一些开发时在社区中引发了有意义的讨论的其他特性。.

针对(项目发展的)路线图对产品特性进行比较，以便于确认产品目标是一致的还是存在分歧的；

原因: 社区会用到这些发布的版本，我们构建的生态系统会基于这些版本构建产品，这两者都需要知道发布的版本中包含了哪些特性，移除了哪些特性；

在该项的总结中添加一个新特性和值得注意的特性的文档链接是有意义的；

非代码内容

总结“非代码内容”的相关状态，包括用户手册、本地化/外部化、样例、教程、相关文章等等；已经存在的一些(非代码的)内容有被更新吗？有新的内容吗？ 废弃的内容有被移除掉或者打上记号以标识出是旧材料吗?

原因: “非代码内容”对于版本的广泛传播与采纳是必不可少的(参考 Eclipse生态系统).

接口

确保这次发布包含的接口满足Eclipse质量要求的；项目领导需要亲自确认相关接口有达到质量要求，并对任何的不足（如果存在）进行讨论；

原因:Eclipse成员会几月可扩展的框架构建商用工具，所以接口的质量尤为重要；

结构问题

总结发布的版本的结构的质量，论述该项目所体现出的可扩展性的本质是什么，以及一些其他问题，比如：和其他项目之间的重复问题、合并不同的组件带来的问题等等；

原因: Eclipse 成员会基于可扩展的框架构建商用的工具，所以结构的质量尤为重要；

安全问题

在你的版本发布之前，检查Bugzilla上的 已解决的缺陷 和提交者当前所私有的缺陷（两者之间可能有交集) 以确定是否存在影响你项目代码的缺陷； 同时检查Bugzilla上因为安全性而还未被标记(解决)的问题(比如：在bug总结中搜索“缺陷”或“安全性”这样的关键字)；

在文档的该部分，描述了你应当做哪些事情，来修正可能由这些缺陷引发的问题

工具的可用性

总结工具的可用性。这里所说的可用性指的是使用工具去解决开发中的问题，而不是理论上的用户接口可用，可测试。

原因: 没有这些可用的工具，项目就吸引不到用于构建Eclipse生态系统的用户(参社区考

三个社区)。

生命周期的结束

总结此次发版后，上个版本中的哪些接口和重要的用户特性将被结束其生命周期（废弃掉或者是被移除掉；

原因: 社区会依赖这些特性来构建产品，所以当这些特性发生变化时，他们是需要知情的； (参考三个社区).

Bugzilla

总结Bugzilla的相关情况，状态为打开、关闭、延期解决、新建等状态的bug(包括缺陷和功能增强的建议)分别有多少，难度为P1、P2等类型的未解决的bug有多少；

原因: bugzilla记录的总结为项目的生产力提供了一个概要图，同样也为未解决的问题所带来的风险提供了一个估算；同时该总结也会被用来提醒社区去了解相关的问题； (参考链接).

标准

总结该版本所承诺的标准。这些特性是建立在确定的、未确定的、还是专门的标准之上，这些标准的状态是什么，还有该版本中这些标准的相关支持的状态是什么；

原因: Eclipse基于相关标准构建框架以及工具，所以我们必须确保有遵循相应的标准。 (参考链接).

用户接口的可用性

总结用户接口的可用性，以及和用户接口指南的一致性，包括508条款的承诺，语言包的一致性（代码是否支持多种语言）等等；对于和标准以及用户指南之间的差异，请加以解释和说明；

原因: 用户社区比简简单单的挥舞鼠标、讲英语、电脑操作工要大得多。我们需要支持更大的社区 (参考用户接口指南 ).

计划表

论述初始的计划表，以及在该版本的开发过程中的计划变更； 也就是说, 项目小组取得的成就是什么；论述里程碑是否有达到；

原因: 社区依赖Eclipse的进度表的一致性，以便于相关项目和产品可以对依赖进行正确地计划；.

社区

总结项目的三个社区的发展状态；考虑bugzilla上的互动、邮件列表、新闻组、公共电话会议、博客、公共关系活动、代码交流活动、 会议专题报道、和其他Eclipse项目或开源项目进行协作(Apache, ObjectWeb,等等)

原因: 对于Eclipse项目而言，围绕其自身构建一个社区才是重中之重，而不仅仅是为其他某个项目提供代码支持，这个回顾项是用于描述社区的成功构建； (参考 三个社区).

知识产权问题

依照 Eclipse 知识产权政策，必须完成一下步骤：

1. 项目领导需要核实：

○ 依照法律文档指南，关于文件和许可文件需要放在对应的位置；

○ 所有的贡献（代码、文档、图片等）都必须由基金会的成员或者签署了相应的提交者协议的人所提交；这两者都有签署、并将遵守Eclipse知识产权政策的。

○ 所有的有重大意义的贡献都有通过基金会法务人员的评审。包括所有许可的到IPZilla(用于跟踪知识产权净值调查的一个网站)的引用；

○ 所有的非提交者提供的代码贡献（包含第三方库）都需要在发布的版本中进行记录，并通过基金会法务人员的评审；包括所有许可的到IPZilla(用于跟踪知识产权净值调查的一个网站)的引用；

○ 必须完成所有的贡献调查表；

○ 所有特性的“版权所属”项必须设置为版权的拥有者 (Eclipse基金会一般不会是版权的拥有者)。

○ 发布中所包含的所有第三方的标志或商标都必须使用EPL许可。

○ 发布物(比如PDF或者EPS文件)中所包含的所有字体或者相似的第三方图片都必须使用EPL许可；

2. 项目管理委员会需要提供一个包含如下内容项目日志：

1. 所有的第三方软件（需要包含相应的许可信息）

2. 所有总要的贡献

3. 所有贡献者的名字（包含通过漏洞修复进行贡献的非提交者）

4. 一个包含任何非标准条款的“关于文件”（比如，对于除EPL之外的许可的引用）；

3. EMO会检查贡献调查表是否有被正确地提交，以及EMO的审批是否有被完成。.

4. Eclipse法务小组审核并批准过的项目日志文件的副本是版本评审文档的一部分。它可以被包含在评审文档中，也可以是单独的文档的形式。

产品特性和组件的提供者的名字必是“Eclipse+项目名称”的形式。怎样给项目一个有意义且时尚的描述取决于PMC。避免使用特殊字符（比如“：”或“-”），除非这些字符是项目名称的一部分。避免使用缩写（除非是像XML或PHP这类软件产业中的通用缩写）。标题必须使用大写: 不需要大写的词包含：条款（首字母除外）、并列连词（如but和or），介词（首字母和尾字母除外）以及不定式中的“to”，相关讨论，请参考Bug 252813.

有知识产权问题请立即说出来

在版本评审的过程中，Eclipse管理机构需要明确地进行询问：是否有成员认为这次发布侵犯了他们的知识产权；如果有，Eclipse管理组织以及该项目需要依照Eclipse知识产权政策和对应的成员进行商讨；

原因:  Eclipse基金会给其成员提供的一个重要的好处是 Eclipse知识产权政策的一致性应用，这确保了(但不担保)框架和工具可以被运用在商业化的产品中去；(参考链接)

项目计划

2008年，12月11日，董事会通过决议：一个项目要通过延续（项目的延续）评审、毕业（项目完结）评审或版本评审，必须按照EMO规定的格式提供一份当前的项目计划，并开放给社区；

如果存在下个版本的项目计划（完整的计划或是草图），完成版本评审的最后一件事情便是公布该项目计划；

准备相关文档

关于文档

文档必须包含上面两章所提到的所有问题；

如需样例，可以从 档案室中获取之前的版本评审文档，或者使用模板(开放式的办公表格格式)。

评审过程

自从评审的内容被创建依赖，版本评审需要进行哪些操作都已经在Development_Resources/HOWTO/Review_Process上进行了描述；

评审成功后应该做什么

在版本评审成功地通过了EMO的投票并获得其认同之后：

1. EMO会发送一封邮件至项目开发列表，肯定改成评审的成功性；

2. 然后，当最终的发布文件准备完毕后，项目组需要将这些文件发送给下载服务器，以便让强大的复制系统通过各种各样的渠道去发布这些内容；

其他结果

版本评审可能包含以下其他结果：

● 延期 –出现了了一些问题，必须在解决后才能继续进行发布；

● 通过，但是备有注意事项 –该次发布存在一些问题，但是这些问题可以通过发布说明或者发布文档进行处理；

● 通过，但是存在一些问题 -该次发布存在一些问题，但是在评审中已同意将这些问题遗留给将来的版本进行处理；

● 失败 – 该版本或者该项目存在重大的问题；