Contributing to Ameba

Sharing/分享 Resources/資源
1

Contributing to Ameba

The Ameba Arduino/SDK/MicroPython codebase are 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.

Code Acceptance

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.

Coding Style

Ameba Coding Style mostly adopt 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.

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 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 review is quicker and easier.

Reporting bugs

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.

GitHub pull requests

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.
  • You should always write commits that allow publication. They must not contain confidential information, references to private documents, links to intranet locations or rude language.
  • 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. GitHub tracks who reviewed what and when.
  • All new features and enhancements require documentation, tests and user guides for us to accept them. Please link each pull request to all relevant documentation and test pull requests.
  • Avoid merging commits. (Always rebase when possible.)
  • Avoid force pushing when making review changes, unless you’re cleaning up your branch’s history once the changes have been approved.
  • Comment in the pull request on every change (rebase or new commits). This helps reviewers to be up to date with changes
  • Smaller pull requests are easier to review and faster to integrate. Use dependencies – split your work by pull request type or functional changes. To add a third-party driver, send it in a separate pull request, and add it as a dependency to your pull request.

See 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 ).

2 Likes