Orbit/IP Log

Note: The contents of this page are retained for historical significance. Please see https://github.com/eclipse/orbit#readme for current information.

Overview

Orbit projects need to have a common way to keep track of the IP information for all versions of the project. In an effort to make this easier, we will put an XML file for each bundle into the orbit releng project in HEAD, and it will contain all of the information for that bundle and all of its versions.

The Orbit IP Log for each bundle is in CVS, in the ip_logs subdirectory of the org.eclipse.orbit.releng project. This directory holds an XML file by the name of each bundle, which contains the following information.

• Browse the latest ip_logs

The "Notes" slot of a bundle's IP Log is also used to generate the "Notes" column on the download pages. This can be used to add interesting information for bundle consumers, such as who's already consuming the bundle in the current Release Train.

• Orbit Download pages, example: R20080807 build

Format

The file format is a work-in-progress but here is what we have so far.

<!-- The "ip_log" element is the root element for the file. It has a version number
     that will increase with changes to the file format.
  -->
<!ELEMENT ip_log project+>
<!ATTLIST ip_log version CDATA #REQUIRED>

<!-- A "project" element represents a specific version of an Orbit project. The
     "id" is the bundle symbolic name and the "version" is the project version.
     The "status" attribute is used to indicate whether or not this project is
     ready for use by consumers. A value of "done" means that its good, and a value of 
     "in-progress" means that it is currently under development.
  -->
<!ELEMENT project info contact notes legal+>
<!ATTLIST project
     id CDATA #REQUIRED
     version CDATA #REQUIRED
     status (done|in-progress) "in-progress"
>

<!-- An "info" element contains more information on the project including where we got 
     it and optional references on the web, etc. -->
<!ELEMENT info (name? origin? reference? repository location tag?)>

<!-- The "name" is a human-readable name for the project. -->
<!ELEMENT name (#PCDATA)>

<!-- The "origin" is the originating individual or company for the project. -->
<!ELEMENT origin (#PCDATA)>

<!-- The "reference" a URL or reference to the original project. (e.g. web site) -->
<!ELEMENT reference (#PCDATA)>

<!-- The "repository" is the path to the CVS repository. -->
<!ELEMENT repository (#PCDATA)>

<!-- The "location" is the path in the CVS repository. -->
<!ELEMENT location (#PCDATA)>

<!-- The "tag" is the CVS tag or branch for the project. -->
<!ELEMENT tag (#PCDATA)>

<!-- The "contact" element describes the person on Orbit who is the contact for that project. -->
<!ELEMENT contact (name? email company?)>
<!ELEMENT email (#PCDATA)>
<!ELEMENT company (#PCDATA)>

<!-- The "notes" element is an area for free-form notes about the project. -->
<!ELEMENT notes (note+)>
<!ELEMENT note (#PCDATA)>

<!-- The "legal" element describes the legal items related to the project. There can be more 
     than one if we have more than one package (JAR, package, or some other unit that has a 
     different license than the enclosing project) The "package" element is not required (and 
     there should only be one "legal" element) if the "legal" element applies to the whole project. 
  -->
<!ELEMENT legal (ipzilla license package?)>
<!ELEMENT ipzilla>
<!ATTLIST ipzilla 
     bug_id CDATA #REQUIRED
>
<!ELEMENT license (name? reference)>
<!ELEMENT package (#PCDATA)>

Example

Fake example for Xerces:

<ip_log version="1.0">
	<project id="org.apache.xerces" version="2.8.0" status="done">
		<info>
			<name>Apache Xerces</name>
			<origin>Apache</origin>
			<reference>http://xerces.apache.org</reference>
			<repository>/cvsroot/tools</repository>
			<location>org.eclipse.orbit/org.apache.xerces</location>
			<tag>v2_8_0</tag>
		</info>
		<contact>
			<name>Joe Smith</name>
			<email>joe@exmample.com</email>
			<company>Example Company</company>
		</contact>
		<notes>
			<note>We use this bundle for parsing XML.</note>
		</notes>
		<legal>
			<ipzilla bug_id="103"/>
			<license>
				<name>Apache License Version 2.0</name>
				<reference>http://apache.org/licenses/LICENSE-2.0</reference>
			</license>
			<package>xerces-apis.jar</package>
		</legal>
		<legal>
			<ipzilla bug_id="1234"/>
			<license>
				<name>Apache License Version 2.1</name>
				<reference>http://apache.org/licenses/LICENSE-2.1</reference>
			</license>
			<package>xerces-impl.jar</package>
		</legal>
	</project>
</ip_log>

Template

Here is a template for you to use. It contains the elements that most bundles will need. If you have a more complex bundle (for instance you ship multiple JARs with multiple licenses) then you will have to modify it.

<ip_log version ="1.0">
	<project id="${bundle_symbolic_name}" version="${version}" status="${status}">
		<info>
			<name>${bundle_name}</name>
			<origin>${origin}</origin>
			<reference>${reference}</reference>
			<repository>/cvsroot/tools</repository>
			<location>org.eclipse.orbit/${bundle_symbolic_name}</location>
			<tag>${branch_or_tag}</tag>
		</info>
		<contact>
			<name>${contact_name}</name>
			<email>${contact_email}</email>
			<company>${contact_company}</company>
		</contact>
		<notes>
			<note>${note_1}</note>
			<note>${note_2}</note>
		</notes>
		<legal>
			<ipzilla bug_id="${ipzilla_id}"/>
			<license>
				<name>${license_name}</name>
				<reference>${license_url}</reference>
			</license>
		</legal>
	</project>
</ip_log>

Original Discussions

Background

Orbit projects need to have a common way to keep track of the IP information for all versions of the project. In an effort to make this easier, we will put an XML file in each project root in HEAD and it will contain all of the information for that project and all of its versions.

• MartinO: Having a file in HEAD of each project requires committers to switch branches for editing it. This seems awkward. I'd prefer one single central file holding IP info for all bundles and versions under Orbit. This would be easier accessible, and allow reviewing other bundle's entries - for instance, in order to copy & paste hyperlinks to common license files like ASF 2.0 or ASF 2.1. I don't think we have that many bundles or high change rate that we'd have to fear running into frequent parallel change and merge issues by a single centralized file.

• Jeff: Good point. How about this. In the Orbit Releng project have an "ip_log" folder and in there have one file per bundle that falls out of Orbit. That file would be named 'bundle id'.xml and would contain the info as described below. I am hesitant to just have one large file as it will be harder for people to find all the information relevant to a particular bundle (which is likely to be the more frequent query. However, having everything in one location is a great win.

• Bjorn: I believe that Eclipse Legal wants to have one file per bundle -version that contains the IP log information for that bundle for that version. I could be wrong. I have asked Janet to comment as well.

• Janet: I like Jeff's suggestion. It will ensure that all of the information is available in one place, while making it easy to identify bundle specific information and where that bundle specific information is missing. This level of clarity will be increasingly important as Orbit grows.

• DJ: Ok, for now we will go with the following story: there will be a /ip_log directory in the org.eclipse.orbit.releng project and in this directory there will be one file per bundle. (my_bundle_name.ip_log) Each file will contain all the IP info for all versions of that bundle.

We would like to be able to use all of the information in this file to produce a suitable web page that describes the project(s) including links to the project in CVS (via ViewCVS) and links to the project on the originating site.

TODO

Section for things we still have to add to the file, including:

• Links to the origin of the code - pointers to the actual binary that we used as input and also maybe a pointer to the source. This could be useful to track the source of eventual problems.

• Martin: I think we should also have a "used-by" section listing all the projects at Eclipse.org which are known to actually use a bundle/version (i.e. include it in one of their features). A hyperlink into ViewVC for the CVS/SVN version of the feature project would perhaps be most helpful. This would not only track usage, but also help other projects who want to adopt it get started with their own feature.xml / feature.properties. When I'm not mistaken, from a legal standpoint every project needs to put an Orbit bundle it wants to pick up through review for usage in their project, so it seems natural to maintain the list of known users.
  • Gunnar: IMHO it would be better if the users only need to specify a reference to an Orbit bundle in their IP log together with their approval CQ. Based on this a list of users could be generated and we would know which projects to contact in case of issues with an Orbit bundle. Having to record this info in two places (a projects IP log and the Orbit bundle IP log) is likely to get one into a stale state.

• Gunnar: The IP log format need to be enhanced to allow multiple licenses, multiple CQs and multiple contacts.