1Contributions Guide 2=================== 3 4We welcome contributions to the ``esptool.py`` project! 5 6How to Contribute 7----------------- 8 9Contributions 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>`_. 10 11.. _development-setup: 12 13Development Setup 14----------------- 15 16Development mode allows you to run the latest development version from the `esptool.py repository on GitHub <https://github.com/espressif/esptool>`_. 17 18.. code-block:: sh 19 20 $ git clone https://github.com/espressif/esptool.git 21 $ cd esptool 22 $ pip install --user -e . 23 24This 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. 25 26It’s also possible to run the scripts directly from the working directory with this Development Mode installation. 27 28To 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: 29 30:: 31 32 $ pip install --user -e ".[dev]" 33 34(This command uses the “extras” feature of setuptools.) 35 36Reporting Issues 37---------------- 38 39Please report bugs in ``esptool.py`` if you find them. However, before reporting a bug please check through the following: 40 41* `Troubleshooting Guide <https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html>`_ - common problems and known issues. 42 43* `Existing Open Issues <https://github.com/espressif/esptool/issues>`_ - someone might have already encountered this. 44 45If you don’t find anything, please `open a new issue <https://github.com/espressif/esptool/issues/new/choose>`_. 46 47Sending Feature Requests 48------------------------ 49 50Feel free to post feature requests. It’s helpful if you can explain exactly why the feature would be useful. 51 52There 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. 53 54Before Contributing 55------------------- 56 57Before sending us a Pull Request, please consider this list of points: 58 59* Have you tried running ``esptool.py`` test suite locally? 60 61* Is the code adequately commented for people to understand how it is structured? 62 63* Is there documentation or examples that go with code contributions? 64 65* Are comments and documentation written in clear English, with no spelling or grammar errors? 66 67* 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/>`_? 68 69* If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback. 70 71Code Style & Static Analysis 72^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 73 74Please follow these coding standards when writing code for ``esptool.py``: 75 76Pre-commit checks 77""""""""""""""""" 78 79`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. 80 81To use the tool, first install ``pre-commit`` and then the git hooks: 82 83:: 84 85 $ python -m pip install pre-commit 86 $ pre-commit install 87 88On 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. 89 90Flake8 91"""""" 92 93``esptool.py`` complies with `flake8 <http://flake8.readthedocs.io/en/latest/>`_ style guide enforcement. 94 95Black 96""""" 97 98All files should be formatted using the `Black <https://black.readthedocs.io/en/stable/index.html>`_ auto-formatter. 99 100``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). 101 102When you submit a Pull Request, the GitHub Actions automated build system will run automated checks using these tools. 103 104Automated Integration Tests 105^^^^^^^^^^^^^^^^^^^^^^^^^^^ 106 107The test directory contains a `pytest <https://docs.pytest.org/>`_ integration suite with some integration tests for ``esptool.py``, ``espefuse.py``, and ``espsecure.py``. 108 109It is necessary to have ``esptool.py`` installed (see `Development Setup`_) in your environment in order to run these tests. 110 111The following tests run automatically by GitHub Actions for each Pull Request. You can run them locally to check for regressions in the respective functionality: 112 113* ``test_imagegen.py`` tests the ``elf2image`` command 114* ``test_image_info.py`` tests the ``image_info`` command 115* ``test_mergebin.py`` tests the ``merge_bin`` command 116* ``test_modules.py`` tests the modules used by ``esptool.py`` for regressions 117* ``test_espsecure.py`` tests ``espsecure.py`` functionality 118 119The 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: 120 121* ``test_esptool.py`` contains integration tests for ``esptool.py`` and needs to be run against real Espressif hardware with the following format: 122 123 ``pytest test_esptool.py --port <serial port> --chip <name of chip> --baud <baud rate>`` 124 125 For example, to run all tests on an ESP32 board connected to /dev/ttyUSB0, at 230400bps: 126 127 ``pytest test_esptool.py --port /dev/ttyUSB0 --chip esp32 --baud 230400`` 128 129 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: 130 131 ``pytest test_esptool.py --port /dev/ttyUSB2 --chip esp8266 --baud 460800 -k TestFlashing`` 132 133 .. note:: 134 135 Some tests might fail at higher baud rates on some hardware. 136 137The following tests are not run automatically by GitHub Actions, but can be run locally in a command line: 138 139* ``test_espefuse.py`` tests ``espefuse.py`` functionality. To run it: 140 141 ``pytest test_espefuse.py --chip <name of chip>`` 142 143 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. 144 145 .. warning:: 146 147 Do not attempt to run these tests on real hardware! You risk damaging or destroying the ESP chip! 148 149The whole test suite (without the tests needing an actual hardware) can be easily run with the following command in the esptool root folder: ``pytest --ignore=test/test_esptool.py`` 150 151 152Pull Request Process 153-------------------- 154 155.. note:: 156 157 If you are developing the stub flasher and plan to send a pull request, please use the latest toolchains available. 158 159After you open the Pull Request, there will probably be some discussion in the comments field of the request itself. 160 161Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing. 162 163If this process passes, it will be merged onto the public github repository, hooray! 164
