This document serves as a checklist before contributing to this repository. It includes links to read up on if topics are unclear to you.
This guide mainly focuses on the proper use of Git.
To report a bug/request please file an issue in the right repository (example for Arduino_Core_STM32). But check the following boxes before posting an issue:
-
Make sure you are using the latest STM32 core and libraries versions.See latest core here. -
Your issue is NOT a question/feedback/suggestions.This should be discussed on the:- stm32duino Github discussions
- stm32duino forum:
- questions on the STM32 Core.
- bugs/enhancements on the STM core: Bugs and enhancements.
-
Make sure your issue is not already reported/fixed on GitHub or discussed on the forumSee stm32duino forum. -
Make sure you are working on the right repository.See the table below.
| Repositories | Projects |
|---|---|
| STM32 Core | Arduino core support for STM32 based boards |
| STM32 Tools | Contains several tools (upload, scripts,...) |
| STM32 Examples | Arduino library to provide examples related to STM32 |
| Board Manager Files | Storage for Arduino Boards Manager JSON file |
| CMSIS module | Mainly storage |
| SVD Files | Mainly storage |
| STM32 Libraries for Arduino IDE | Search on the STM32duino GitHub repository |
When you have checked the previous boxes. Please consider the following points before posting the issue.
-
Describe the issue based on the behaviour you were expecting -
Post complete error messages using markdown code fencing:Markdown Code Fencing Example -
Provide a full set of steps necessary to reproduce the issue -
Demonstration code should be complete, correct and the minimum amount necessary to reproduce the issue
About Pull Requests
An easy to read pull request will speed up the merging process. Your commit messages need to be logically separate. And containing enough information on their own. When this is done consistently your pull request will have an easy to read log of changes.
Your commits need to be atomic which allows the repository to remain flexible after merging.
If you did not read the following 7 points before or just want to fresh up. Please read up on them on this website by Chris Beams.
- Separate subject from body with a blank line
- Limit the subject line (first line) to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
(.) - Use the imperative mood in the subject line. This should be in the written as giving an instruction for example "Fixed save-as bug" (it shows what the PR achieves when merging it)
- Wrap body at 72 characters
- Use the body to explain what, why and how
If your pull request fixes, closes or resolves an issue please reference it in the body with the following syntax. Also see the last lines of the following example.
A general example with these 7 guidelines in mind is shown below (from the same website of Chris Beams):
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
When different people are working on the Arduino project simultaneously, pull requests can go stale quickly. A "stale" pull request is one that is no longer up to date with the latest merges in the project. It needs to be updated before it can be merged.
Most often pull requests become stale when merge conflicts occur. This happens when two pull requests both modify similar lines in the same file and one gets merged, the unmerged request will now have a merge conflict and needs updating.
When your pull request is stale, you will need to rebase your branch on the current main branch before you can merge it without conflicts.
More information about rebasing can be found at the repository of edX.
Run the checks relevant to the files you changed and include the commands and important results in the pull request description.
- Documentation changes must pass the strict MkDocs build (see the documentation workflow to set up the environment):
"$HOME/.venvs/stm32duino-docs/bin/mkdocs" build --strict - Changes under
cores/,libraries/orvariants/must pass the AStyle check (see Code style):python3 CI/astyle/astyle.py -g - For source changes, also run the applicable build, example or test checks for the affected board families.
When your pull request is merged please update the related documentation if the change affects user-facing behavior, supported boards, examples, build options, or upload and debugging workflows. Documentation
Use the guide that matches the type of change:
- Using the Git repository: how to work with a local core checkout.
- Adding a board variant: new generic and dedicated board variants.
- Code style and AStyle: required formatting and local validation commands.
- Documentation workflow: how to edit, build, preview, and publish documentation.
- Source locations: the main core and board-package directories.