stlink/CONTRIBUTING.md

Contribution guidelines

Contributing to the stlink project

We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:

• Reporting a bug
• Discussing the current state of the code
• Submitting a fix
• Proposing new features
• Assistance with maintaining

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests. Report a bug by opening a new issue with one of the available templates. It's that easy!

NOTE: In order to offer sufficient and the best possible support, please read and follow the instructions below before submitting a ticket:

1. If using a ST-Link-v2 programmer: Convince yourself that it is recognised as an USB device by your computer, thus reporting device and manufacturer ID. Use a diagnostic tool to probe for enumerated USB devices, e.g lsusb -v on unix-based systems.
2. Use the ST-Link firmware upgrade tool based on Java to read out the current firmware version and update to the latest available version. This also works for non-genuine ST programmers and boards.
3. Try to make sure you have a working toolchain before starting to build.
4. Update to the latest release version or maybe even use the develop branch.
5. Search for your problem in the available open issues, before opening a new ticket.
6. Make sure to use the available issue templates to submit a bug-report or a feature-request. Do not replace the prepared text, edit the placeholders instead. Describe your problem.
7. Avoid to add new comments to closed issues unless they confirm a solution already available.
8. Don't comment on tickets which do not specifically address your device or hardware - open a new ticket instead.
9. Consider if you can help to solve other issues (e.g. you have the same hardware)

Coding conventions

To read code written by other contributors can turn out to be quite demanding - a variable which seems to self-explaining, may appear cryptic to other readers. If you plan to contribute, please take this into account and feel encouraged to help others understand your code. In order to help you along, we have composed some contribution guidelines for this project. As this project already has a history you may find parts in the codebase that do not seem to comply with these guidelines, but we are trying to improve continuosly. However we can do even better, if every contributor considers the following points:

• Naming of all source code elements as well as comments should exclusively be written in English.
• All functions and global variables should be fully explained. This includes a short description on what the respective function does (but not necessarily how this is achieved), an explantion of transfer parameters and/or return values (if applicable).
• Use fixed width integer types wherever possible and size-appropiate datatypes.
• Only make use of the datatype char for specific characters, otherwise use int8_t or uint8_t respectively.

Coding Style

• Use 4 spaces for indentation rather than tabs (the latter results in inconsistent appearance on different platforms)
• Use /* your comment */ formatting for multi-line comments or section titles and // your comment for inline comments.
• Please try to avoid special characters where possible, as they are interpreted differently on particular platforms and systems. Otherwise these may result in mojibake within the sourcecode or cause translation errors when compiling.
• Use state-of-the-art UTF-8 encoding whereever possible.

Github Flow

We Use Github Flow which implies that all code changes happen through Pull Requests (PRs). They are the best way to propose changes to the codebase and we actively welcome your own ones:

1. PRs should focus on one single topic.
2. Fork the repo and create your branch from develop.
3. Begin to implement your changes on a local or personal branch.
4. Take a look at existing PR and check if these target the same part of the codebase. Should this be the case, you are encouraged to get in touch with the respective author and discuss on how to proceed.
5. Keep your personal feature-branch up to date with the current development branch, by merging in recent changes regularly.
6. Don't open a PR unless your contribution has evolved to a somehow completed set of changes.
7. If you've changed major features, update the documentation.
8. Ensure your PR passes our travis CI tests.
9. Issue that pull request!

License

When you submit code changes, your submissions are understood to be under the same BSD-3 License that covers this project.
Feel free to contact the project maintainers should there be any related questions.