diff --git a/en/design/API-Review-Template.md b/en/design/API-Review-Template.md new file mode 100644 index 0000000000000000000000000000000000000000..3621ffe351f08cd70047b287137c2607af4a1fe3 --- /dev/null +++ b/en/design/API-Review-Template.md @@ -0,0 +1,137 @@ +# Review Application for the API in the OpenHarmony Subsystem + +## Background + +* API type: [Public API | Test API | HDI] +* API requirement source: +* API usage scenario: +* Belonging subsystem: +* Expected API release version: +* Contributor: +* Number of APIs involved in this review: + +| Change Type| Quantity| Programming Language| +|---|---|---| +| Added| | | +| Behavior changed| | +| Deprecated| | | +| Deleted| | | + +## API Description + +### Necessity of the Changes + +> Based on the as-is and gap analysis, describe what the application scenarios and benefits of the APIs are. + +### Feature Overview + +> Describe features implemented by the APIs. + +## Review Conclusion + +### Review conclusion from committers: + +### Review conclusion from domain SIGs: + +## Self-Check Table + +| Self-Check Item| Self-Check Result| +|---|---| +| Is the spelling check completed?| | +| Are coding specifications complied with?| | +| Are parts of speech (noun, adjective, adverb) used correctly?| | +| Does the API name fully describe the API logic?| | +|Is the number of API parameters appropriate? (Generally, there should be fewer than 7 parameters.)| | +|Are abbreviations properly used? (Abbreviations used should be well known.)| | +|Is it really that the caller of a void API does not need a return value?| | +|Is the inheritance system appropriate? Does every method of a parent class apply to its child classes?| | +|Are all possible error states included and defined?| | +| Is the group of antonyms used correctly, for example:
add/remove, create/destroy, insert/delete, start/stop, begin/end,
send/receive, up/down, show/hide, open/close, source/target,
source/destination, increase/decrease, first/last, next/previous| | +|Are the description and semantic hierarchy of new APIs consistent with those of existing APIs in the same module?| | +| Are asynchronous counterparts needed for synchronous APIs?| | +| Are all the public APIs truly required by developers?| | + +## API Description + +> Enter the code commit address. + +* Code address: + +## API Permission Design + +> Specify whether developers need to apply for certain permissions to use the APIs. + +## API Privacy Protection Design + +> If user privacy data is involved, privacy protection must be considered. + +## Developer Guide + +> Optional. + +## API Code Example + +> Select either of the following: + +* Code address: +* Code snippet: + +## API Updates + +> Only required for existing APIs. + +### Behavior Change + +> The API behavior change indicates that the API only has its behavior changed. +> The new API behavior must be released in a new version. You should not change the API behavior without releasing a new version (except for defect rectification). + +#### Related APIs + +#### Reason for the Change + +### Deprecated APIs + +> Add the `@deprecated` annotation to the description of deprecated APIs (including JS, TS, C, and C++ APIs). + +#### Related APIs + +> State the version from which the API is annotated by `@deprecated`. + +#### Reason for Deprecation + +#### Substitute APIs + +> List the APIs provided to substitute the deprecated ones. If there are no substitute APIs provided, describe the reason. + +### Deleted APIs + +> An API can be deleted only after five API versions have been released since it is marked as deprecated. + +#### Related APIs + +#### Reason for Deletion + +#### Substitute APIs + +> List the APIs provided to substitute the deleted ones. If there are no substitute APIs provided, describe the reason. + +## DFX + +### Compatibility + +### Performance + +### Power Consumption + +### Reliability + +### Testability + +> Automatic API test cases must be delivered for all APIs. + +## Review Conclusion + +* Reviewed on: +* Reviewers: +* Review conclusion: [Pass | Fail] +* Review meeting minutes: diff --git a/en/design/OpenHarmony-API-governance.md b/en/design/OpenHarmony-API-governance.md index d117bf795c8979d66234470535554885e009ab72..1fc38f9d8a5ee53c0da60d0bf85694305f469857 100644 --- a/en/design/OpenHarmony-API-governance.md +++ b/en/design/OpenHarmony-API-governance.md @@ -136,10 +136,7 @@ Design APIs from the perspective of their users rather than providers. ### Compatibility -1. The API compatibility requirements in descending order are as follows: contract compatibility > binary-code compatibility > source-code compatibility. - 1. Source-code compatibility: After version evolution, the developer’s existing source code can be compiled properly. - 2. Binary-code compatibility: After version evolution, the developer’s existing programs can be linked to and run properly without recompilation. - 3. Contract compatibility: It is also called semantic compatibility. After version evolution, the developer’s original program behaviors remain unchanged. +1. 2. OpenHarmony API backward compatibility must meet binary-code compatibility requirements. Exceptions must be reviewed by the API SIG and approved by the PMC. Common API changes that break binary-code compatibility include: 1. Delete any API elements. 2. Reduce the visibility of a method. For example, change from protected to private or from public to protected. diff --git a/en/design/figures/API-Category.png b/en/design/figures/API-Category.png new file mode 100644 index 0000000000000000000000000000000000000000..0d4fc2f8b42c36eb7bfa8b907a299a0fd3fb2bb6 Binary files /dev/null and b/en/design/figures/API-Category.png differ diff --git a/en/design/figures/API-Definition.png b/en/design/figures/API-Definition.png new file mode 100644 index 0000000000000000000000000000000000000000..fc11d7e85845fdc3f80513f0bfbf042f2cd6592c Binary files /dev/null and b/en/design/figures/API-Definition.png differ diff --git a/en/design/figures/API-Lifecycle.png b/en/design/figures/API-Lifecycle.png index 79c15efb497d93778c2399afe25e6b2034624a42..63da45189ca31b5f9d0a826a07f6f090b97cec32 100644 Binary files a/en/design/figures/API-Lifecycle.png and b/en/design/figures/API-Lifecycle.png differ diff --git a/en/design/figures/API-Workflow.png b/en/design/figures/API-Workflow.png new file mode 100644 index 0000000000000000000000000000000000000000..41a41b6f19dc9a3001e7914d066810910a211622 Binary files /dev/null and b/en/design/figures/API-Workflow.png differ diff --git a/zh-cn/design/figures/API-Workflow.png b/zh-cn/design/figures/API-Workflow.png index e65960d8bdbcb19b4f4cda4dce16a71ce229c227..d9f4eecc35e0c2d2af92cab0c79d16a4b3807086 100644 Binary files a/zh-cn/design/figures/API-Workflow.png and b/zh-cn/design/figures/API-Workflow.png differ