165 lines
7.8 KiB
ReStructuredText
165 lines
7.8 KiB
ReStructuredText
Contributions Guide
|
||
===================
|
||
|
||
We welcome contributions to the ``esptool.py`` project!
|
||
|
||
How to Contribute
|
||
-----------------
|
||
|
||
Contributions to ``esptool.py`` - fixing bugs, adding features, adding documentation - are welcome. We accept contributions via `Github Pull Requests <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_.
|
||
|
||
.. _development-setup:
|
||
|
||
Development Setup
|
||
-----------------
|
||
|
||
Development mode allows you to run the latest development version from the `esptool.py repository on GitHub <https://github.com/espressif/esptool>`_.
|
||
|
||
.. code-block:: sh
|
||
|
||
$ git clone https://github.com/espressif/esptool.git
|
||
$ cd esptool
|
||
$ pip install --user -e .
|
||
|
||
This will install ``esptool.py``’s dependencies and create some executable script wrappers in the user’s ``bin`` directory. The wrappers will run the scripts found in the git working directory directly, so any time the working directory contents change it will pick up the new versions.
|
||
|
||
It’s also possible to run the scripts directly from the working directory with this Development Mode installation.
|
||
|
||
To also install additional tools needed for actually developing and testing ``esptool.py``, run this command to install a development copy of ``esptool.py`` *plus* packages useful for development:
|
||
|
||
::
|
||
|
||
$ pip install --user -e ".[dev]"
|
||
|
||
(This command uses the “extras” feature of setuptools.)
|
||
|
||
Reporting Issues
|
||
----------------
|
||
|
||
Please report bugs in ``esptool.py`` if you find them. However, before reporting a bug please check through the following:
|
||
|
||
* `Troubleshooting Guide <https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html>`_ - common problems and known issues.
|
||
|
||
* `Existing Open Issues <https://github.com/espressif/esptool/issues>`_ - someone might have already encountered this.
|
||
|
||
If you don’t find anything, please `open a new issue <https://github.com/espressif/esptool/issues/new/choose>`_.
|
||
|
||
Sending Feature Requests
|
||
------------------------
|
||
|
||
Feel free to post feature requests. It’s helpful if you can explain exactly why the feature would be useful.
|
||
|
||
There are usually some outstanding feature requests in the `existing issues list <https://github.com/espressif/esptool/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement>`_, feel free to add comments to them.
|
||
|
||
Before Contributing
|
||
-------------------
|
||
|
||
Before sending us a Pull Request, please consider this list of points:
|
||
|
||
* Have you tried running ``esptool.py`` test suite locally?
|
||
|
||
* Is the code adequately commented for people to understand how it is structured?
|
||
|
||
* Is there documentation or examples that go with code contributions?
|
||
|
||
* Are comments and documentation written in clear English, with no spelling or grammar errors?
|
||
|
||
* If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits <https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_?
|
||
|
||
* If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback.
|
||
|
||
Code Style & Static Analysis
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Please follow these coding standards when writing code for ``esptool.py``:
|
||
|
||
Pre-commit checks
|
||
"""""""""""""""""
|
||
|
||
`pre-commit <https://pre-commit.com/>`_ is a framework for managing pre-commit hooks. These hooks help to identify simple issues before committing code for review.
|
||
|
||
To use the tool, first install ``pre-commit`` and then the git hooks:
|
||
|
||
::
|
||
|
||
$ python -m pip install pre-commit
|
||
$ pre-commit install
|
||
|
||
On the first commit ``pre-commit`` will install the hooks, subsequent checks will be significantly faster. If an error is found an appropriate error message will be displayed. If the error was with ``black`` then the tool will fix them for you automatically. Review the changes and re-stage for commit if you are happy with them.
|
||
|
||
Flake8
|
||
""""""
|
||
|
||
``esptool.py`` complies with `flake8 <http://flake8.readthedocs.io/en/latest/>`_ style guide enforcement.
|
||
|
||
Black
|
||
"""""
|
||
|
||
All files should be formatted using the `Black <https://black.readthedocs.io/en/stable/index.html>`_ auto-formatter.
|
||
|
||
``Black`` and ``flake8`` tools will be automatically run by ``pre-commit`` if that is configured. To check your code manually before submitting, run ``python -m flake8`` and ``black .`` (the tools are installed as part of the development requirements shown at the beginning of this document).
|
||
|
||
When you submit a Pull Request, the GitHub Actions automated build system will run automated checks using these tools.
|
||
|
||
Automated Integration Tests
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
The test directory contains a `pytest <https://docs.pytest.org/>`_ integration suite with some integration tests for ``esptool.py``, ``espefuse.py``, and ``espsecure.py``.
|
||
|
||
It is necessary to have ``esptool.py`` installed (see `Development Setup`_) in your environment in order to run these tests.
|
||
|
||
The following tests run automatically by GitHub Actions for each Pull Request. You can run them locally to check for regressions in the respective functionality:
|
||
|
||
* ``test_imagegen.py`` tests the ``elf2image`` command
|
||
* ``test_image_info.py`` tests the ``image_info`` command
|
||
* ``test_mergebin.py`` tests the ``merge_bin`` command
|
||
* ``test_modules.py`` tests the modules used by ``esptool.py`` for regressions
|
||
* ``test_espsecure.py`` tests ``espsecure.py`` functionality
|
||
* ``test_espsecure_hsm.py`` tests support of extarnal HSM signing in ``espsecure.py``. These tests require additional prerequisites, see ``SoftHSM2 setup`` in the `tests workflow definition <https://github.com/espressif/esptool/blob/master/.github/workflows/test_esptool.yml>`_ for more information.
|
||
|
||
The following tests are not run automatically by GitHub Actions, because they need real connected hardware. Therefore, they need to be run locally in a command line:
|
||
|
||
* ``test_esptool.py`` contains integration tests for ``esptool.py`` and needs to be run against real Espressif hardware with the following format:
|
||
|
||
``pytest test_esptool.py --port <serial port> --chip <name of chip> --baud <baud rate>``
|
||
|
||
For example, to run all tests on an ESP32 board connected to /dev/ttyUSB0, at 230400bps:
|
||
|
||
``pytest test_esptool.py --port /dev/ttyUSB0 --chip esp32 --baud 230400``
|
||
|
||
Or to run the TestFlashing suite only (using the pytest ``-k`` option to select tests based on their name) on an ESP8266 board connected to /dev/ttyUSB2, at 460800bps:
|
||
|
||
``pytest test_esptool.py --port /dev/ttyUSB2 --chip esp8266 --baud 460800 -k TestFlashing``
|
||
|
||
.. note::
|
||
|
||
Some tests might fail at higher baud rates on some hardware.
|
||
|
||
The following tests are not run automatically by GitHub Actions, but can be run locally in a command line:
|
||
|
||
* ``test_espefuse.py`` tests ``espefuse.py`` functionality. To run it:
|
||
|
||
``pytest test_espefuse.py --chip <name of chip>``
|
||
|
||
These test use the ``--virt`` virtual mode of ``espefuse.py`` to safely test the functionality without a connection to a chip and without the possibility of affecting the actual eFuses in a real hardware.
|
||
|
||
.. warning::
|
||
|
||
Do not attempt to run these tests on real hardware! You risk damaging or destroying the ESP chip!
|
||
|
||
The whole test suite (without the tests needing an actual hardware or installation of additional prerequisites) can be easily run with the following command in the esptool root folder: ``pytest -m host_test``
|
||
|
||
|
||
Pull Request Process
|
||
--------------------
|
||
|
||
.. note::
|
||
|
||
If you are developing the stub flasher and plan to send a pull request, please use the latest toolchains available.
|
||
|
||
After you open the Pull Request, there will probably be some discussion in the comments field of the request itself.
|
||
|
||
Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing.
|
||
|
||
If this process passes, it will be merged onto the public github repository, hooray!
|