THIS IS A DRAFT DOCUMENT
What are CQs for?
CQs all for the management and tracking of references to and distribution of third-party artifacts. Roughly speaking they serve three parties:
- Eclipse Consumers: CQs and the IP log generated from them, allow consumers to know what they are buying into when they consider using your project.
- Eclipse IP team: CQs enable the IP team to review and track the use and distribution of third-party artifacts.
- PMCs: CQs give the PMCs visibility into their project's relationship to the world outside Eclipse. They are then able to guide projects to similar function in Eclipse, help in generalizing infrastructure choices and ensure vendor-neutrality.
What does it mean to "distribute" something?
If something is freely available from an eclipse.org server, then it is being distributed by Eclipse. Examples are (but not limited to): downloads, CVS/SVN/GIT, bugzilla, mailing lists, eclipse.org blogs, ... So putting some third party code in your project's CVS repo is distribution regardless of whether or not the project includes the library in a release.
What is "defacto" or "implied" distribution?
Even if your project's zip file or release repository does not include a particular third party artifact, if project's function requires that the artifact be acquired by the projects consumer, then you have implicitly distributed that artifact. Works-with dependencies capture cases where that distribution is optional.
What does it mean to "reference" some third party artifact?
References to third-party code can be found in source code (e.g., Java, C, ...), configuration files, build files (scripts, POMs, ...). So, a Java file that imports the org.junit package references Junit. Simiarly, a POM.xml that lists hibernate.jar as a dependency references Hibernate.
What is a "dependency"?
Any situation where Eclipse software is designed to call or otherwise invoke third party software - even through indirect means - creates a "dependency" on the third party software. Such dependencies may require approval by the EMO.
What is a "works-with" dependency?
- The Eclipse software does not require the third party software to be present. If the third party software happens to be present, the Eclipse software may call or invoke it. Example: If a web browser is present, clicking on URL's in Eclipse will cause the user's configured web browser to open the URL. or
- The Eclipse software is designed to work with multiple third party software choices that provide similar functionality - the choice of which to use is up to the user. At least one of those must be a pre-req (see below) or approved by the EMO for distribution by the project. Example: If a project requires a persistence mechanism, it can allow the user to select from several different implementations.
What is the purpose of the works-with dependencies?
put IP policy wording here
When contemplating optional work-with status for an artifact, what factors should be considered?
The key thing here is whether or not the project requesting the dependency largely works without the third-party artifact. If it does and is simply enhanced in performance or function with the addition of the dependency then it likely qualifies as an optional works-with.
Do I enter CQs for works-with dependencies?
Not immediately. You first consult in an open and transparent way with your PMC to gain approval for your proposed works-with dependency. Once that approval is granted, your relationship with the library is tracked by opening a CQ and referencing the mailing list discussion that approved the use.
Can works-with dependencies be version-independent?
Yes. Works-with dependencies are for tracking loosely coupled relationships to third-party code that is not distributed directly by your project. It makes sense in many cases to be version independent.
What are prereq dependencies?
A "Pre-req Dependency" is where the Eclipse software requires the third party software in order to work correctly or to provide full function. Example: Eclipse pre-req's Apache Ant.
"Pre-req" dependencies fall into two cases: "exempt pre-req" and "non-exempt pre-req". This determination is made by the EMO with input from the relevant PMC and project leadership.
- A pre-req may be classified as "exempt" by the EMO if the software is pervasive in nature, expected to be already on the user's machine, and/or an IP review would be either impossible, impractical, or inadvisable. Exempt pre-req's can be approved for use by the EMO without IP review. Examples: Windows XP, Sun JRE. However, an exempt pre-req may be disallowed by the EMO at its discretion.
- If a pre-req is non-exempt, it must go through the IP review process and be approved or non-approved for use as a pre-req.
My project's releases do not include a particular third party lib and only use it for testing. Do I need to do anything in IP-land? If so, what? (and why?)
By their very nature test are optional function for a project. A project should work perfectly fine without its tests. The addition of tests (and the third party artifacts they may need) enhances the project's output by adding testability. As such, an artifact needed solely for testing purposes can be covered by works-with dependencies.
Our build fetches a lib from some non-eclipse.org repo (e.g., Maven Central) but the lib is not part of the release. What now?
Since your project is referencing the third-party artifact, you need to document this. If it truly is just a testing related dependency then talk with your PMC about a works-with relationship. Otherwise, enter a normal CQ.
Do I need to enter a CQ if I have a dependency on another Eclipse project?
It depends. You don't strictly need to enter a CQ if you depend upon code that was developed within the other Eclipse project, but if the code was brought into the project through a CQ then you will need to enter a CQ. The safest approach is to first engage the PMC on the mailing list and then enter a CQ with a comment stating the exact part of the Eclipse project that you depend upon.