Skip to main content
Jump to: navigation, search

Difference between revisions of "MicroProfile/SpecChecklist"

(Mandatory deliverables)
(Mandatory deliverables)
Line 10: Line 10:
 
* A '''hand-written document''' - describes the expected behavior and intended usage of the API (also known as the Specification)
 
* A '''hand-written document''' - describes the expected behavior and intended usage of the API (also known as the Specification)
 
* '''Technology Compatibility Kit (TCK)''' (source code, JAR artifact, user guide) - provides a test suite to verify an implementation of the specification
 
* '''Technology Compatibility Kit (TCK)''' (source code, JAR artifact, user guide) - provides a test suite to verify an implementation of the specification
 +
  
 
If the specification doesn't describe Java API, it should deliver an analogous deliverable (e.g. Swagger/OpenAPI REST definitions, JSON/XML schemas or similar).
 
If the specification doesn't describe Java API, it should deliver an analogous deliverable (e.g. Swagger/OpenAPI REST definitions, JSON/XML schemas or similar).
 +
 +
* '''Compatible Implementation''' - Although a Compatible Implementation is not delivered with any MicroProfile component release, an open-source implementation needs to be available in some form when a Component declares a final release.  This demonstrates that the Specification is implementable and that the TCK actually works.  This early implementation does not have be "production ready" nor does it even have to be a Generally Available release.  All that is required is that an end user of a given Component release could access this implementation, build it (if required), and execute the TCK against it.
  
 
=== Optional deliverables ===
 
=== Optional deliverables ===

Revision as of 15:14, 14 January 2019

Specification Delivery Checklist

This page covers all common rules for deliverables of any specification.

Types of Deliverables

Mandatory deliverables

  • API with Javadocs (source code, javadoc, API JAR artifact, schema files) - defines the contract between the implementation and its consumers
  • A hand-written document - describes the expected behavior and intended usage of the API (also known as the Specification)
  • Technology Compatibility Kit (TCK) (source code, JAR artifact, user guide) - provides a test suite to verify an implementation of the specification


If the specification doesn't describe Java API, it should deliver an analogous deliverable (e.g. Swagger/OpenAPI REST definitions, JSON/XML schemas or similar).

  • Compatible Implementation - Although a Compatible Implementation is not delivered with any MicroProfile component release, an open-source implementation needs to be available in some form when a Component declares a final release. This demonstrates that the Specification is implementable and that the TCK actually works. This early implementation does not have be "production ready" nor does it even have to be a Generally Available release. All that is required is that an end user of a given Component release could access this implementation, build it (if required), and execute the TCK against it.

Optional deliverables

The following can be provided loosely with the specification, before or after it's released:

  • Sample applications (using the new specification)
  • Sample implementation(s)
  • List of compliant implementations

Checklist for deliverables

  • 3rd Party Dependency clearance
    • Each 3rd Party Dependency needs to be identified and cleared for usage. This includes all open-source and commercial software used by our MicroProfile runtime, build, and test processing. More info can be found in 3rd Party Dependency Process
  • Proper license and attribution
    • each file has the same Copyright&License header, a NOTICE file in each repository and deliverable - see more info in Guidelines for contributing
  • Proper maven artifact naming
    • groupId: org.eclipse.microprofile.subproject-name for subprojects, org.eclipse.microprofile for the top level distribution (BOM, etc)
    • artifactId: microprofile-<subproject>-<submodule>
    • see more info in Guidelines for contributing
  • Java API
  • OSGi bundle information

Back to the top