Contributing to Ameba
⚠️ The Ameba Arduino/SDK/MicroPython codebase is hosted on GitHub, you can submit new features or bug fixes using Pull Request on Github. Before you do so, please read the Coding Style and Contribution Guideline section.
Once submit your pull request, our developers will take a look and comment on the pull request. If all is well and acceptable, your code will be ready for merging into the central development branch.
Ameba Coding Style mostly adopts from Mbed OS. Whether you're writing new code or fixing bugs in existing code, please follow the Ameba coding style.
Ameba follows the K&R style -- Variant: 1TBS, with a few exceptions，
- 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.
- 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))).
- Use lower case letters
- Words separated by a capital letter of the subsequent work (readDir, getRootPath).
Before contributing an enhancement (for example, a new feature or new port), please discuss it on the forums or on the Facebook group 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.
You can submit Ameba bugs directly on GitHub. Please submit questions or enhancement requests on the forums or on the Facebook group
The bug report should be reproducible (fails for others) and specific (where and how it fails). We will close insufficient bug reports.
❗ Important: All Pull Requests are to be submitted to
devbranch, PR to master branch will not be accepted
- Changes pertaining to software only
- Changes pertaining to additional hardware
- Contributor-maintained features
For the software-only PRs, contents of which should be placed under path as follows,
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 dev. 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 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
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,
- The purpose/use of this feature
- How to use this feature
- In which version of SDK was the feature tested
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 ).
