如何開始貢獻

對」Ameba MicroPython SDK <https://github.com/ambiot/ambd_micropython>」的貢獻包括：」添加功能」，」添加/修改文檔」，」修復錯誤」。在這樣做之前，請閱讀：ref：』coding-style’和：ref：』contribution-guide』。

備註

**Ameba Arduino/SDK/MicroPython**代碼庫託管在GitHub上，您可以使用」Github Pull Requests <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>」_提交新功能或錯誤修復。

代碼接受

在根據「指南<https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>」向我們發送拉取請求之前。

默認拉取請求應在「dev」分支上進行。提交拉取請求后，我們的開發人員將查看並評論拉取請求。

如果一切都很好並且可以接受，您的代碼將準備好合併到「master」分支中。

編碼風格

Ameba的編碼風格大多采用Mbed OS。無論你是編寫新的代碼還是修復現有代碼中的bug，請遵循Ameba的編碼風格。

除了下面幾種特殊情況，大部分情況下 Ameba 程式碼都遵循 K&R style – Variant: 1TBS,

  • Indentation - four spaces. Please do not use tabs.

  • Braces - K&R style. One true brace style (1TBS)

  • One line per statement.

  • Each line preferably has at most 120 characters.

  • Space after statements of type if , while , for , switch . The same applies to operators (like, +, = and * ) and the ternary operator ( ? and : ).

  • For pointers or references, the symbols * or & are adjacent to a type ( analogin_t* obj . analogin_t& obj ).

  • Empty lines should have no trailing spaces.

  • Use capital letters for macros.

  • Preprocessor macro starts at the beginning of a new line; the code inside is indented according to the code above it.

Naming conventions

Classes

  • Begin with a capital letter, and each word within a class also begins with a capital letter (AnalogIn, BusInOut).

  • Private members start with an underscore: __User defined types (typedef))) .

Functions

  • Use lower case letters

  • Words separated by a capital letter of the subsequent work (readDir, getRootPath).

Contribution Guideline

Before contributing an enhancement (for example, a new feature or new port), please discuss it on Ameba Forum or on the Facebook group [EN]/ [ZH] to avoid duplication of work, as we or others might be working on a related feature.

We can only accept contributions through GitHub if you create a Pull Request from forked versions of our repositories. This allows us to review the contributions in an easy-to-use and reliable way, under public scrutiny.

Please create separate Pull Requests for each topic; each Pull Request needs a clear unity of purpose. In particular, separate code formatting and style changes from functional changes. This makes each Pull Request’s true contribution clearer, so the review is quicker and easier.

Reporting Bugs

You can submit Ameba Bugs directly on GitHub. Please submit questions or enhancement requests on the Ameba Forums or on the Facebook group [EN]/ [ZH] The bug report should be reproducible (fails for others) and specific (where and how it fails). We will close insufficient bug reports.

GitHub Pull Request (PR)

重要

❗ All Pull Requests are to be submitted to dev branch, PR to master branch will not be accepted

Categories of PR

Software PRs

For the software-only PRs, contents of which should be placed under path below:

https://github.com/ambiot/ambd_arduino/tree/dev/Arduino_package/hardware

Note that code submitted under this path will be actively tested and maintained by the official development team. Please test the new software feature with the latest release version before submitting a PR.
Other than that, software PR can be the easiest/fastest to be reviewed and merged.

For people who wants to contribute to the Ameba ReadtheDocs online documentation repository. Please following the guide for Sphinx-based documentations and make Pull Request.

Hardware PRs

For the contributed items that require extra hardware implementation/products, it is recommended that the contributed content can be saved as a .ZIP library which can be easily installed using Arduino IDE’s built-in function.

Such libraries should be stored in the path below:

https://github.com/ambiot/ambd_arduino/tree/master/Arduino_zip_libraries

備註

Detailes of preparing a .ZIP library can be found here

Contributors-maintained PRs

If you have created some features which you would love to actively maintain, yet still make it known and easily accessible by other community members, you may consider updating your work to the following path in the form of a readme: https://github.com/ambiot/ambd_arduino/tree/master/Ameba_misc

Details of your work should include:

  1. The purpose/use of this feature

  2. How to use this feature

  3. In which version of SDK was the feature tested

Requirements of PR

Pull Requests on GitHub have to meet the following requirements to keep the code and commit history clean:

  • Commits must always contain a proper description of their content. Start with a concise and sensible one-line description. Then, elaborate on reasoning of the choices made, descriptions for reviewers, and other information that might otherwise be lost.

  • Because we use GitHub, special commit tags that other projects may use, such as “Reviewed-by”, or “Signed-off-by”, are redundant and should be omitted.

  • All new features and enhancements require documentation(at least an easy-to-follow readme), tests for us to accept them.

  • Avoid merging commits. (Always rebase whenever possible to keep commit history clean)

  • Smaller Pull Requests are easier to review and faster to integrate.

See the example here:

Update early access SDK 3.0.9-build20210408

    Feature:
    - support board RTL8720DN_BW16
    - update Eink lib
    API Updates:
    - pre support Microsoft Azure IoT cloud
    -- enable "strnlen" from rom
    -- add "#define yield" for compilation
    - update SPI, I2C, Fatfs, Audiocodec and UART for RTL8720DN_BW16
    Misc:
    - add RTL8720DN_BW16 frizting folder

If commits do not follow the above guidelines, we may request that you modify the commit history (often to add more details to address what and why rather than how ).