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"
(→Checklist for deliverables: OSGi) |
(→Checklist for deliverables) |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 8: | Line 8: | ||
* '''API with Javadocs''' (source code, javadoc, API JAR artifact, schema files) - defines the contract between the implementation and its consumers | * '''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 | + | * 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 | + | * '''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 === | ||
| Line 18: | Line 21: | ||
* Sample applications (using the new specification) | * Sample applications (using the new specification) | ||
| − | * | + | * Additional sample implementation(s) |
| − | * List of compliant implementations | + | * List of [https://wiki.eclipse.org/MicroProfile/Implementation compliant implementations] |
== Checklist for deliverables == | == Checklist for deliverables == | ||
| + | * Release record created | ||
| + | ** As soon as a MicroProfile Component or Platform release is looking real, a corresponding Release record should be created via the [https://projects.eclipse.org/projects/technology.microprofile/governance Governance page]. These Release records announce a forthcoming release -- like a roadmap. You should not wait until the release is final to create a Release record. | ||
| + | ** These Release records are used by the Eclipse team to plan for the review process (CQ reviews, IP reviews, IP scans, etc). It also announces our team's plans for releases that are coming down the road for our end users. | ||
| + | ** Eclipse Release Reviews are the 1st and 3rd Wednesdays of each month. Also, plan for a two week review cycle. If your Component release is part of a MicroProfile Platform release, then the Platform release review takes care of the work effort. But, if your Component release falls outside of a Platform release timeline, then you'll need to perform your own Eclipse review. | ||
* 3rd Party Dependency clearance | * 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 [[MicroProfile/3rdPartyDependencyProcess | 3rd Party Dependency Process]] | ** 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 [[MicroProfile/3rdPartyDependencyProcess | 3rd Party Dependency Process]] | ||
Revision as of 16:55, 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)
- Additional sample implementation(s)
- List of compliant implementations
Checklist for deliverables
- Release record created
- As soon as a MicroProfile Component or Platform release is looking real, a corresponding Release record should be created via the Governance page. These Release records announce a forthcoming release -- like a roadmap. You should not wait until the release is final to create a Release record.
- These Release records are used by the Eclipse team to plan for the review process (CQ reviews, IP reviews, IP scans, etc). It also announces our team's plans for releases that are coming down the road for our end users.
- Eclipse Release Reviews are the 1st and 3rd Wednesdays of each month. Also, plan for a two week review cycle. If your Component release is part of a MicroProfile Platform release, then the Platform release review takes care of the work effort. But, if your Component release falls outside of a Platform release timeline, then you'll need to perform your own Eclipse review.
- 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.