diff --git a/en/contribute/template/figures/figure01.png b/en/contribute/template/figures/figure01.png new file mode 100644 index 0000000000000000000000000000000000000000..df3c115b78a0c8bb792c704735dd6e213a2d1e6c Binary files /dev/null and b/en/contribute/template/figures/figure01.png differ diff --git a/en/contribute/template/figures/figure02.png b/en/contribute/template/figures/figure02.png new file mode 100644 index 0000000000000000000000000000000000000000..159b193f425237a47ca351a8d093060a08f27d20 Binary files /dev/null and b/en/contribute/template/figures/figure02.png differ diff --git a/en/contribute/template/readme-template.md b/en/contribute/template/readme-template.md new file mode 100644 index 0000000000000000000000000000000000000000..5533ad43fcf16ed0915a4eebe55b2f69e6ea5bca --- /dev/null +++ b/en/contribute/template/readme-template.md @@ -0,0 +1,155 @@ +# ***ExampleName*** Subsystem/Part + +- [Introduction](#Introduction) +- [Directory Structure](#Directory-Structure) +- [Constraints](#Constraints) +- [Compilation and Building](#Compilation-and-Building) +- [Usage](#Usage) + - [Available APIs](#Available-APIs) + - [Usage Guidelines](#Usage-Guidelines) +- [Repositories Involved](#Repositories-Involved) + +[Title Description] Use **Subsystem** or **Part** based on the Readme file type. + + +![Subsystem-readme](figures/figure01.png) + + +## Introduction + + +[Writing Instructions] **Mandatory**. The following contents must be included: + +**Overall introduction.** Describe the subsystem from the following aspects: background (role in the entire OpenHarmony architecture), functions, use cases, and supported devices. + +**Architecture diagram.** Provide an architecture diagram and explain the main components in the architecture. + +**If this document is about a part, which is part of a subsystem, and related concepts of the subsystem can help understand the part, you are advised to include the following information:** + +**For more concepts related to the ***exampleName*** subsystem, see ***exampleName***. (Provide the link to the subsystem readme.)** + + +The precautions for writing are as follows: + + +| Item| Requirement| +| -------- | -------- | +| **A.1** | **Content**| +| A.1.1 | Style: Use formal language and avoid colloquial language.| +| A.1.2 | Compliance: Do not use terms that have compliance and legal risks, such as concepts specific to third-party intellectual property rights.| +| A.1.3 | Concise: Provide only necessary and minimum information to instruct developers to complete operations as soon as possible.| +| A.1.4 | Correct: The code and parameters in the Readme file must be consistent with the actual product information.| +| A.1.5 | Accurate: Use accurate rather than ambiguous description.| +| A.1.6 | Consistent: Words and concepts in the Readme file must be used consistently across the file and compliant with the glossary. The full name of an acronym or abbreviation must be provided when it appears for the first time in the file.| +| A.1.7 | Specific: Use specific words. For example, when indicating the quantity or degree, do not use "more" or "less". Use specific numbers instead.| +| **A.2** | **Format**| +| A.2.1 | Use punctuation correctly. End a sentence with punctuation.| +| A.2.2 | Present the content clearly, for example, by using bullets or categories. Do not include a single bullet or extra empty lines.| +| A.2.3 | Do not add a space between an English word and Chinese word.| +| A.2.4 | Use valid and specific links that provide direct redirection or download. It is recommended that relative links in Gitee instead of absolute links be used.| +| A.2.5 | For auxiliary description, use the "Note" format. For declaration in advance, use the "Notice" format.| +| **A.3** | **Tables**| +| A.3.1 | Include a caption for each table. Use nouns or noun phrases in the caption.| +| A.3.2 | Include a header for each table. Ensure that a table contains at least two rows and two columns.| +| A.3.3 | If there is no content in a table cell, use an underscore (_) in the cell, rather than leaving it blank.| +| **A.4** | **Figures**| +| A.4.1 | Do not include figures of religious beliefs.| +| A.4.2 | Include a caption for each figure. Use nouns or noun phrases in the caption.| +| A.4.3 | Figures must be clear, legible, complete, and easy to read. For example, a flowchart must contain "Start" and "End".| +| A.4.4 | Each figure must have clear logic and be provided with relevant text descriptions.| +| A.4.5 | It is recommended that each figure, in .png format, have the size less than or equal to 150 KB, the height about 640 px, and the width less than or equal to 820 px.| +| A.4.6 | Try not to include text in figures. If text is required, make sure the text language is consistent with your file's language.| + + +The following shows an architecture diagram. Pay attention to the **color and format requirements**. + +**Figure 1** Subsystem architecture +![Architecture](figures/figure02.png) + + + +## Directory Structure + +[Writing Instructions] **Mandatory**. Describe the code directory structure of the project repository and function description of the corresponding directory. + +```undefined +/foundation/ace +├── frameworks # Framework code +│ └── lite +│ ├── examples # Sample code +│ ├── include # Exposed header files +│ ├── packages # JS implementation +│ ├── src # Source code +│ ├── targets # Configuration file of each target device +│ └── tools # Tool code +├── interfaces # APIs exposed externally +│ └── innerkits # Header files for internal subsystems +│ └── builtin # Third-party module APIs provided by the JS application framework +``` + + + +## Constraints + +[Writing Instructions] **Optional**. Include the conditions for project running, for example, a specific programming language or a specific operating system with a given version. + +| Item| Requirement| +| -------- | -------- | +| D.1.1 | Clearly specify the function limitations or operation restrictions.| +| D.1.2 | Describe only constraints that affect task development or user experience.| +| D.1.3 | Describe operations that are prone to errors in the procedure, but not in this section.| + + +## Compilation and Building + +[Writing Instructions] **Optional**. This section is not required for a subsystem Readme file. Include this section in a part Readme file based on the actual conditions. + + +## Usage + + +### Available APIs + +[Writing Instructions] **Optional**. Describe the APIs related to the development guide so that developers can have a general understanding of the APIs before development. **This section is not required for a subsystem Readme file.** Determine whether this section is required for a part Readme file based on the actual conditions. If the corresponding API reference is available, you do not need to include this section. The precautions for writing are as follows: + +| Item| Requirement| +| -------- | -------- | +| J.1.1 | Include only APIs relevant to the development task.| +| J.1.2 | Provide only main APIs if there are too many APIs.| + + +### How to Use + +[Writing Instructions] **Optional**. Provide a concept introduction for a subsystem Readme file and function introduction for a part Readme file. If the corresponding development guide is available, you can provide a link, rather than details here. + +The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one. + +| Item| Requirement| +| -------- | -------- | +| **F.1** | **Writing a Development Procedure**| +| F.1.1 | Complete: Provide all mandatory steps.| +| F.1.2 | Clear: The logic of the writing must be clear and reasonable. The overview, preparations, and operations in the document must be described by following certain logic, and the chapters should not be broken or contradictory.| +| F.1.3 | Sentence pattern for tasks: Use verbs + nouns to describe actions in titles or sentences.| +| F.1.4 | Prevention in advance: If the operation involves restrictions, errors, or potential risks, describe them in advance.| +| F.1.5 | Clear steps-1: Describe the purpose of each step, no matter whether it is simple or not.| +| F.1.6 | Clear steps-2: Specify the environment, tools, operations, and how-to.| +| F.1.7 | If an operation is optional, specify the conditions in which the operation is required.| +| F.1.8 | After the development procedure is complete, specify the expected results.| +| **F.2** | **Writing a Code Segment**| +| F.2.1 | If a code segment involves commands to be copied by developers, display the commands in editable mode, instead of using screenshots. Use code snippets to wrap the commands.| +| F.2.2 | Provide comments for key sections and key steps in the code.| +| F.2.3 | The code display meets the code indentation requirements.| +| F.2.4 | If an API call is involved in a step, provide the API and its usage description or sample code. The code should come from specific instances.| + + +## Repositories Involved + +[Writing Instructions] **Mandatory**. List the links of all related repositories of the subsystem where the current repository is located and mark the current repository in bold. + +Example: + +[Kernel](https://gitee.com/openharmony/docs/blob/master/en/readme/kernel-subsystem.md) + +[drivers\_liteos](https://gitee.com/openharmony/drivers_liteos/blob/master/README.md) + +**kernel\_liteos\_a** \ No newline at end of file diff --git a/en/contribute/template/xxboard-template.md b/en/contribute/template/xxboard-template.md new file mode 100644 index 0000000000000000000000000000000000000000..1d2f96eee083e9f81f45cdbec5c302476af94727 --- /dev/null +++ b/en/contribute/template/xxboard-template.md @@ -0,0 +1,81 @@ +# ***ExampleName*** Development Board +*Template positioning: When a third-party development board is introduced to OpenHarmony, the board vendor needs to provide an introduction to the board for developers to quickly understand the board.* + +## Introduction + +*[Writing Instructions]* + +*Describe the functions, scenarios, and key features supported by the development board.* + +*Provide a picture to show the appearance of the development board.* + +*Provide a bottom board picture.* + +*Provide a functional block diagram and an introduction.* + +*Name the figures after the development board.* + +*Reference document: https://gitee.com/openharmony/docs/blob/master/en/device-dev/quick-start/quickstart-lite-introduction-hi3861.md* + +******** +## Development Board Specifications + +*[Writing Instructions] Provide the module and hardware specifications of the development board.* + +## (Optional) Constraints + +*[Writing Instructions] Describe the restrictions and suggestions on functions, features, and specifications of the development board, if any.* + +******** + + +## Key Features +*[Writing Instructions] List supported key features of OpenHarmony.* + +## Pin Definition +*[Writing Instruction] Describe the definitions of I/O pins, and how to configure pins and connect pins to external components.* + +## Setting Up the Development Environment + +### System Requirements + +*[Writing Instruction] Describe the dependency of the development board on the OpenHarmony system, software environment, and hardware environment.* + +### Required Tools + +*[Writing Instruction] Provide the paths for downloading the tools used to build and debug the development board.* + +### Setup Process + +*[Writing Instruction] Describe the procedure for setting up the environment step by step.* + +## Building and Debugging + +### Building + +*[Writing Instruction] Describe how to use OpenHarmony and update OpenHarmony binary files and devices on the development board.* + +### Burning + +*[Writing Instruction] Describe how to burn images step by step.* + +### Running + +*[Writing Instruction] Describe how to check whether the lighting, running, and output of the development board are proper.* + + +### Debugging + +*[Writing Instruction] Describe how to debug common errors on the development board.* + +## First Demo + +*[Writing Instruction] Provide a quick start example and running effect based on the development board, or provide the link of the demo source code.* + +## References + +*[Writing Instruction] Provide links to the reference documents, samples, and FAQs.* + +## (Optional) Acknowledgments + +*[Writing Instruction] Provide acknowledgements to third-party contributors.* diff --git a/en/release-notes/Readme.md b/en/release-notes/Readme.md index 6a8faf8d225ed7f2878bb6fd736a2063c6eb5770..d427ae57aa383f9da13a89072136d265bad8ef52 100644 --- a/en/release-notes/Readme.md +++ b/en/release-notes/Readme.md @@ -1,6 +1,7 @@ # OpenHarmony Release Notes ## OpenHarmony 3.x Releases -[OpenHarmony v3.0 LTS (2021-09-30)](OpenHarmony-v3.0-LTS.md) +- [OpenHarmony v3.1 Beta (2021-12-31)](OpenHarmony-v3.1-beta.md) +- [OpenHarmony v3.0 LTS (2021-09-30)](OpenHarmony-v3.0-LTS.md) ## OpenHarmony 2.x Releases - [OpenHarmony v2.2 beta2 (2021-08-04)](OpenHarmony-v2.2-beta2.md) diff --git a/en/release-notes/api-change/v3.1-beta/changelog-v3.1-beta.md b/en/release-notes/api-change/v3.1-beta/changelog-v3.1-beta.md new file mode 100644 index 0000000000000000000000000000000000000000..3fb8d84259bfe15fde0363c771c586a484a72e95 --- /dev/null +++ b/en/release-notes/api-change/v3.1-beta/changelog-v3.1-beta.md @@ -0,0 +1,42 @@ +# Changelog +##### Key API/Component Changes +## IPC Subsystem +#### cl.rpc.1 sendRequest Return Value Type Change + +##### Change Impact + +The **sendRequest** method in the JS modules **RemoteProxy** and **RemoteObject** is changed to an asynchronous interface. The new version uses a **Promise** object to return a **SendRequestResult** instance. Existing applications need to be adapted. + +##### Key API/Component Changes + +``` +Module: ohos.rpc.IRemoteObject, ohos.rpc.RemoteProxy and ohos.rpc.RemoteObject +Old method: sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): boolean + +New method: +sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): Promise +``` + +**Adaptation Guidelines** + +``` +import rpc from "@ohos.rpc" + +let option = new rpc.MessageOption() +let data = rpc.MessageParcel.create() +let reply = rpc.MessageParcel.create() +proxy.sendRequest(1, data, reply, option) + .then(function(result) { + console.info("send request done") + if (result.errCode === 0) { + // read result from result.reply + } + }) + .catch(function(e) { + console.error("send request failed: " + e) + }) + .finally(() => { + data.reclaim() + reply.reclaim() + }) +``` diff --git a/en/release-notes/api-change/v3.1-beta/js-apidiff-v3.1-beta.md b/en/release-notes/api-change/v3.1-beta/js-apidiff-v3.1-beta.md new file mode 100644 index 0000000000000000000000000000000000000000..6c35b8f2444037cbff85579e3863982163774e45 --- /dev/null +++ b/en/release-notes/api-change/v3.1-beta/js-apidiff-v3.1-beta.md @@ -0,0 +1,427 @@ +# JS API Differences + +This document describes the changes of APIs in OpenHarmony 3.1 Beta when compared with OpenHarmony 3.0 LTS. + +## Standard System API Changes + +| Module| API| Change Type| Change Description| +| -------- | -------- | -------- | -------- | +| System Application - settings| getUri(name: string): string | Added| Added the API for obtaining the URI of a string.| +| System Application - settings| getValue(dataAbilityHelper: DataAbilityHelper, name: string, defValue: string): string | Added| Added the API for obtaining the value of a string in the database.| +| System Application - settings| setValue(dataAbilityHelper: DataAbilityHelper, name: string, value: string): boolean | Added| Added the API for saving a string name and its value in the database.| +| Misc Services - systemTime| getCurrentTime(callback: AsyncCallback): void | Added| Added the API for obtaining the number of milliseconds elapsed since the Unix epoch.| +| Misc Services - systemTime| getCurrentTime(): Promise | Added| Added the API for obtaining the number of milliseconds elapsed since the Unix epoch.| +| Misc Services - systemTime| getCurrentTimeNs(callback: AsyncCallback): void | Added| Added the API for obtaining the number of nanoseconds elapsed since the Unix epoch.| +| Misc Services - systemTime| getCurrentTimeNs(): Promise | Added| Added the API for obtaining the number of nanoseconds elapsed since the Unix epoch.| +| Misc Services - systemTime| getRealActiveTime(callback: AsyncCallback): void | Added| Added the API for obtaining the number of milliseconds elapsed since the system boot, excluding the deep sleep time.| +| Misc Services - systemTime| getRealActiveTime(): Promise | Added| Added the API for obtaining the number of milliseconds elapsed since the system boot, excluding the deep sleep time.| +| Misc Services - systemTime| getRealActiveTimeNs(callback: AsyncCallback): void | Added| Added the API for obtaining the number of nanoseconds elapsed since the system boot, excluding the deep sleep time.| +| Misc Services - systemTime| getRealActiveTimeNs(): Promise | Added| Added the API for obtaining the number of nanoseconds elapsed since the system boot, excluding the deep sleep time.| +| Misc Services - systemTime| getRealTime(callback: AsyncCallback): void | Added| Added the API for obtaining the number of milliseconds elapsed since the system boot, including the deep sleep time.| +| Misc Services - systemTime| getRealTime(): Promise | Added| Added the API for obtaining the number of milliseconds elapsed since the system boot, including the deep sleep time.| +| Misc Services - systemTime| getRealTimeNs(callback: AsyncCallback): void | Added| Added the API for obtaining the number of nanoseconds elapsed since the system boot, including the deep sleep time.| +| Misc Services - systemTime| getRealTimeNs(): Promise | Added| Added the API for obtaining the number of nanoseconds elapsed since the system boot, including the deep sleep time.| +| Misc Services - systemTime| getDate(callback: AsyncCallback): void | Added| Added the API for obtaining the system date.| +| Misc Services - systemTime| getDate(): Promise | Added| Added the API for obtaining the system date.| +| Misc Services - systemTime| getTimeZone(callback: AsyncCallback): void | Added| Added the API for obtaining the system time zone.| +| Misc Services - systemTime| getTimeZone(): Promise | Added| Added the API for obtaining the system time zone.| +| ArkUI Framework - Universal Events| onAreaChange (Component Area Change Event)| Added| Added the API for subscribing to component area (including the size and position) changes.| +| ArkUI Framework - Universal Attributes| responseRegion| Added| Added the attribute for touch hotspot settings.| +| ArkUI Framework - Universal Attributes| touchable| Added| Added the attribute that specifies whether a component is touchable.| +| ArkUI Framework - Universal Attributes| stateStyle| Added| Added the attribute that specifies the styles of the pressed and disabled states of a component.| +| ArkUI Framework - Basic Gestures| SwipeGesture | Added| Added the SwipeGesture module.| +| ArkUI Framework - Basic Components| Marquee | Added| Added the **\** component.| +| ArkUI Framework - Basic Components| PluginComponent | Added| Added the **\** component.| +| ArkUI Framework - Basic Components| TextArea | Added| Added the **\