Skip to content

Latest commit

 

History

History
363 lines (265 loc) · 12.6 KB

CONTRIBUTING.md

File metadata and controls

363 lines (265 loc) · 12.6 KB
Raw

Contribution Guide

Mbed OS is an open source project and we really appreciate your contributions to the tools. We are committed to fostering a welcoming community, please see our Code of Conduct, which can be found here:

There are several ways to contribute:

  • Raise an issue found via GitHub Issues.
  • Open an pull request to:
    • Provide a fix.
    • Add an enhancement feature.
    • Correct, update or add documentation.
  • Answering community questions on the Mbed Forum.

How to Contribute Documentation or Code

Please keep contributions small and independent. We would much rather have multiple pull requests for each thing done rather than have them all in the same one. This will help us review, give feedback and merge in the changes. The normal process to make a change is as follows:

  1. Fork the repository.
  2. Make your change and write unit tests, please try to match the existing documentation and coding style.
  3. Add a news file describing the changes and add it in the /news directory, see the section News Files below.
  4. Write a good commit message.
  5. Push to your fork.
  6. Submit a pull request.

We will review the proposed change as soon as we can and, if needed, give feedback. Please bear in mind that the tools for Mbed OS are complex and cover a large number of use cases. This means we may ask for changes not only to ensure that the proposed change meets our quality criteria, but also to make sure the that the change is generally useful and doesn't impact other uses cases or harm maintainability.

If you are new to developing on Python projects, you may find our development tutorial valuable. We cover how to get a Python development environment set up, how to use tox, and other tips.

News Files

News files serve a different purpose to commit messages, which are generally written to inform developers of the project. News files will form part of the release notes so should be written to target the consumer of the package or tool.

  • A news file should be added for each merge request to the directory /news.
  • The text of the file should be a single line describing the change and/or impact to the user.
  • The filename of the news file should take the form <number>.<extension>, e.g, 20191231.feature where:
    • The number is either the issue number or, if no issue exists, the date in the form YYYYMMDD.
    • The extension should indicate the type of change as described in the following table:
Change Type Extension Version Impact
Backwards compatibility breakages or significant changes denoting a shift direction. .major Major increment
New features and enhancements (non breaking). .feature Minor increment
Bug fixes or corrections (non breaking). .bugfix Patch increment
Documentation impacting the consumer of the package (not repo documentation, such as this file, for this use .misc). .doc N/A
Deprecation of functionality or interfaces (not actual removal, for this use .major). .removal None
Changes to the repository that do not impact functionality e.g. build scripts change. .misc None

Commit Hooks

We use pre-commit to install and run commit hooks, mirroring the code checks we run in our CI environment.

The pre-commit tool allows developers to easily install git hook scripts which will run on every git commit. The .pre-commit-config.yaml in our repository sets up commit hooks to run pytest, black, mypy and flake8. Those checks must pass in our CI before a PR is merged. Using commit hooks ensures you can't commit code which violates our style and maintainability requirements.

To install the commit hooks for the repository (assuming you have activated your development environment as described in the development guide), run:

$ pre-commit install

Our code checks will now run automatically every time you try to git commit to the repository.

If you prefer not to install the hook scripts, you can use

$ pre-commit run

to check your staged changes.

Pull Requests and Commit Messages

We aim to compose and review patchsets, not individual patches. When merging a pull request, we preserve the commit history. Ensure your commit history is clean and understandable.

We recommend the following commit structure in the following order:

  1. Whitespace only changes
  2. Style changes (although we use black to auto format the code so these should be rare)
  3. Refactoring (no functional change)
  4. Meaningful behavioural changes

We also recommend adding a prefix to your commit message to highlight the area of relevance. Write prefixes in lowercase, followed by a colon, followed by a space, and then finally the commit title. Some example prefixes include the following:

  • project:
  • config:
  • tests:
  • docs:
  • cli:
  • travis:
  • ci:

Follow Chris Beams' article on how to write a Git commit message to ensure you're writing good commit messages.

An example commit message

commit 23efe7ba1009a0b0db890df3b940157c732085b7
Author: Vikas Katariya <[email protected]>
Date:   Thu Nov 26 11:36:02 2020 +0000

deploy: Use default branch from remote repository

Make sure we checkout the default branch from the remote repository, if
there is no git hash present in the .lib file.

We also need to fetch the git repository before performing a checkout
when using the `deploy` command. This makes sure we have the latest
changes in the upstream repo.

Fixes #122

Contribution Agreement

Mbed previously required a signed contributor agreement in order to accept contributions. Mbed no longer requires such an agreement. Mbed projects (unless otherwise noted in the specific project) now accept contributions under Apache-2.0 directly. For more details, refer to the Mbed OS contributing guide

Thank you for contributing to mbed-tools.

Development and Testing

For development and testing purposes, it is essential to use a virtual environment. tox is a commonly used development tool that helps manage virtual environments.

Setup Python and tox

mbed-tools is compatible with Python 3.6 or later.

If you are on a Linux distribution, or macOS, you will find that Python comes pre-installed on your system. Do not use the pre-installed versions of Python for development.

Below are links to guides for correctly setting up a development ready version of Python 3 on common platforms:

On Windows we have also found the Python Launcher for Windows to be a reasonable alternative.

After you have set up your Python 3 installation, install tox (the --user flag is important never use sudo to install Python packages!)

On macOS, with the defacto macOS package manager, Homebrew:

brew install tox

On other platforms, use your native package manager's tox package or your Python environment's Python package manager, pip, like so:

python3 -m pip install --user tox

Check that tox is in the binary path

tox --version

If not, find the user base binary directory

python -m site --user-base
#~ /Users/<username>/Library/Python/3.9

Append bin to the directory returned and add this to your path by updating ~/.profile. For example you might add the following:

export PATH=~/Library/Python/3.9/bin/:$PATH

Setup Development Environment

Clone the mbed-tools GitHub repository.

git clone [email protected]:ARMmbed/mbed-tools.git

Set up the development environment using tox (tox will create a development environment at mbed-tools/.venv):

cd mbed-tools/
tox -e dev
source .venv/bin/activate

Unit Tests, Code Formatting and Static Analysis

After you have activated your development environment, run tox -e linting,py39 to run unit tests and static code analysis checks:

tox -e linting,py39

This will run black, flake8, mypy and pytest. If you would like to run these tools individually, see below:

Run unit tests:

pytest

Run code formatter (it will format files in place):

black .

Run static analysis (note that no output means all is well):

flake8

Perform static type check:

mypy src/mbed_tools

Type hints

Type hints should be used in the code wherever possible. Since the documentation shows the function signatures with the type hints there is no need to include additional type information in the docstrings.

Code Climate

Code Climate is integrated with our GitHub flow. Raising a pull request that fails any of the configured rules will prevent your pull request from being merged.

If you prefer to view the Code Climate report on your machine, prior to sending a pull request, you can use the cli provided by Code Climate.

Plugins for various tools are also available:

Documenting code

Inclusion of docstrings is needed in all areas of the code for Flake8 checks in the CI to pass.

We use google-style docstrings.

To set up google-style docstring prompts in Pycharm:

  • in the menu navigate to Preferences > Tools > Python Integrated Tools
  • in the dropdown for docstring format select 'Google'

For longer explanations, you can also include markdown. Markdown can also be kept in separate files in the docs/user_docs folder and included in a docstring in the relevant place using the reST include as follows:

    .. include:: ../docs/user_docs/documentation.md

Building docs locally

You can do a preview build of the documentation locally by running:

generate-docs

This will generate the docs and output them to local_docs. This should only be a preview. Since documentation is automatically generated by the CI you shouldn't commit any docs html files manually. The docs will be generated and checked in as part of the release process.

Viewing docs generated by the CI

If you want to preview the docs generated by the CI you can view them in the Azure pipeline artifacts directory for the build.

Documentation only gets committed back to this repo to the docs directory during a release and this is what gets published to Github pages. Don't modify any of the files in this directory by hand.

Creating a Release

Production releases of mbed-tools are created automatically every night by our continuous delivery system (implemented in Azure Pipelines). There should be no human intervention required to deploy mbed-tools to pypi.

If you wish to create a production release of mbed-tools without waiting for the continuous deployment system to create one, you can perform the following steps:

  1. Check out the master branch; ensure it is clean and up to date.
  2. Run tox -e preprelease, this will update the necessary files, create a commit and tag it with the new release version number.
  3. Push the commit to master.
  4. Push the tag.

The CI will detect a new tag has been created and run the "Build and Deploy" pipeline, which then pushes the release to pyPI.

NOTE: The release process relies on a shell script ci_scripts/prep-release, so will not work on Windows systems.