How to Contribute Fingerprints for OSS Discovery
OSS Discovery uses fingerprints to identify each open source software package. OSS Discovery needs an extensive fingerprint library in order to identify the broadest possible set of open source packages – for The Open Source Census and for enterprises and individuals who want to take inventory of their open source software. A fingerprint (also called a project rule) is made up of a set of criteria that can uniquely identify a particular open source software package. These criteria can include factors such as file names, directories, file contents and checksums. Each project rule attempts to uniquely identify an open source project with the minimal possible set of criteria.
It is important to ensure that each project rule can successfully find the target open source package, while avoiding "false positives" or conflicts with other rules. The process outlined below will help us include as many project rules as possible without creating conflicts with any previously established project rules.
The Project Rule Contribution Process
We'd love to be able to accept new project rules without any vetting, but because it's possible for a new project rule to conflict with an existing rule or be redundant with an existing rule, we have put in place a vetting process for new rule contributions. This is an outline of that process. If you haven't already done so, it would be beneficial to read the documents in the Developer Guide, especially Rule Writing for Discovery 2.
Any new rule contributions should be made using the OSS Discovery Issue Tracker. That way the submission can be fully evaluated and tracked through to inclusion with the next release of fingerprints. The Issue Tracker has an issue type of "Contribution: Project Rule". All the information below should be entered into the body of the issue form, and all contributed files attached to the Contribution: Project Rule issue.
Requirements for new project rules
Before contributing a new rule, please make sure it meets the following criteria.
- A project rule must be able to identify the last 5 years of releases of the submitted project. If a projects is less than 5 years old, the rule should be able to identify all releases.
- A project rule must be able to find all supported platforms of the open source project to which the rule applies.
- A project rule must not have a duplicate project name as an established standard rule (unless the contribution is a fix to an existing rule).
- A project rule must cover an open source project with a valid, approved OSI license.
- You must submit control group content, which are copies of any key files that are needed to test the project rule. This control group content should include, at a minimum, key files from the earliest version, the latest version, and samples for each platform. Attach the control group content to the "Issue Tracker Contribution: Project Rule" issue. See the Developer Guide for more information.
Acceptance process for new project rules
- Once a new project rule has been submitted, it will be combined with existing rules and tested against existing control qroup content to insure rule conflicts do not exist and rule does not result in false positives.
- A project rule will be rejected if it doesn't meet the acceptance criteria above. The contributor will be given the rationale and correction steps if appropriate.
- OSS Discovery committers will determine the appropriate location in which the rule will be incorporated (which rule file).
In order to submit a new rule or defect on an existing rule, you need to register as a user of this site.
Please include the following information in the issue text that you submit:
- Project Name – the project name for which the rule is written
- Project URL – the URL for the main project page
- Location/Source/URL of the package you downloaded – e.g. project site, mirror site, Linux distro, Maven repository, forge, etc
- The rule definition – rule_fragment.xml containing the XML rule definition or modification (attach to issue)
- Control group content needed for testing – earliest and latest versions, platform-specific samples (.zip or tar.gz - attach to issue)
You will also need to sign and submit the OSS Discovery Contributor Agreement – see the License & Legal section of the site for more information.