Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
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 16:14, 14 January 2019
Contents
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
- the CDI API classes should be placed in a subpackage inject - see more info in the Guidelines for Contributing
- OSGi bundle information
- For more info, check out Emily's email.