Skip to content

Library Maintainers Guide

Jump to bottom
David Conran edited this page Nov 23, 2022 · 28 revisions

Library Maintainers Guide & Notes.

Writing code

Code Lint and Style

All of the code in this library (including examples and tools) tries to comply with various style guides. We also have a automated zero-tolerance for lint errors. All commits are subjected to automated style guide & lint checks as part of the checks. You should run these checks prior to committing or sending a PR etc.

General

  • Spaces, not tabs. Indents with two spaces.
  • Limit line lengths to 80 characters. URLs are exempt.
  • For overall style consistency, if there is an available ''Google'' code style guide, follow that.
  • Use meaningful identifiers. Single letter variables etc are really only acceptable for iterators on small loops.
  • Write your code so that it can be unit tested.
  • Write unit tests.
  • These are a guide only, not rules. They can be broken when appropriate. The universe will not end. ;-)

C++

Python

Testing

  • Please write unit tests for your code. They are preferred, not a requirement. However it is good engineering practice to write them.
  • Indicate in your commits/PR if you have/haven't actually tested the code, especially if there are no Unit Tests for it.
  • Run all the existing unit tests before you commit/create a PR. GitHub Actions will also do it but it will email everyone saying something broke. It will save you some embarrassment. ;-)

Code review

  • It is "best practice" to have your code reviewed by someone else prior to submission. Do it, but it's not a hard requirement.
  • If no changes have been requested by a reviewer after a week or so (including no response) you can submit the code.
  • You only need a single review approval before merging.
  • As a reviewer, try to offer constructive advice and if it is trivial, make the change required in the PR if you can.
  • Be kind to first-time or novice contributors, but don't compromise the library to accommodate them obviously.
  • Emergency non-reviewed commits & PRs are fine. Use your common sense. i.e. A trivial change that fixes a bug. Typos etc.

TL;DR: "What the job of a code reviewer entails is someone to check if the code looks sane, would be similar to how they would implement it, check for any obvious boo-boos, offer advice, and offer constructive criticism. A code review(er) is not responsible for making sure there are no bugs, or anything. They are never to blame if something goes wrong. All responsibility is with the code author basically. Not you. So there is little pressure." Quote ref

Unit Tests

The Unit Tests which are under the test/ & tools/ directories are for a Unix machine, not the micro-controller (ESP8266). e.g. For GitHub Actions & the developer's workstation.

All internal library code must use c99 exact-width type definitions. e.g. uint16_t etc. You must disable any Arduino/ESP8266 specific code (e.g. Serial.print() etc.) using something like:

#ifndef UNIT_TEST
<Arduino specific code ...>
#endif

The Unit Tests & Test Coverage are not perfect as we can not emulate hardware specific features and differences. e.g. Interrupts, GPIOs, CPU instruction timing etc, etc.

The example code has no unit tests.

To run the tests yourself, try the following:

$ cd test
$ make install-googletest  # Only ever needs to be run/installed once.
$ make run_tests

Before you create a Pull Request

Pre-commit checklist

This library uses GitHub Actions to ensure all the tests & code style checks pass before allowing a commit/merge to the library. i.e. You might as well run them by hand before you commit your final code. There is no escaping these checks. The full battery of checks performed can be found in the library's .github/workflows/*.yml files. However, the Lazy Developer's guide is as follows.

Have you never run any of the library's tests before?

  1. Install the appropriate tools. This only needs to be done once. e.g.
$ # This all assumes you've got a linux machine with typical dev tools installed. e.g. gcc, g++, python, make, etc.
$ sudo apt-get install pylint3  # Install the Python Linter
$ sudo pip install platformio  # PlatformIO is like the Arduino IDE. It will build/compile the code.
$ pio update  # Ensure PlatformIO is to date.
$ wget https://raw.githubusercontent.com/google/styleguide/gh-pages/cpplint/cpplint.py  # Get the latest C++ linter.
$ cd git/IRremoteESP8266/test
$ make install-googletest

Did you change a file under the examples directory?

  1. Ensure that the example code still compiles without any errors or warnings.
  2. Run the C++ linter from the top directory of the library. Fix any issues it finds. e.g.
$ cd git/IRremoteESP8266
$ cpplint --extensions=c,cc,cpp,ino,h --headers=h,hpp --count=total --verbose=2 {src,src/locale,test,tools}/*.{h,c,cc,cpp,hpp,ino} examples/*/*.{h,c,cc,cpp,hpp,ino}

or

$ cd git/IRremoteESP8266
$ wget https://raw.githubusercontent.com/google/styleguide/gh-pages/cpplint/cpplint.py
$ python ./cpplint.py --extensions=c,cc,cpp,ino --headers=h,hpp {src,src/locale,test,tools}/*.{h,c,cc,cpp,hpp,ino} examples/*/*.{h,c,cc,cpp,hpp,ino}

Did you change a file ending in *.h or *.cpp that was not under the examples directory?

  1. Run the C++ linter from the top directory of the library. Fix any issues it finds. (See above for examples)
  2. Run all the Unit Tests in the test directory. e.g.
$ cd test
$ make install-googletest  # Only ever needs to be run/installed once.
$ make run_tests

Did you change anything under the tools directory?

  1. Make sure the program you edited still compiles/works as expected.
  2. Run the C++ linter (See above)
  3. Run the "tools" tests. i.e.
$ cd tools
$ make run_tests

Did you change a file ending in *.py?

  1. You need to run the python linter. e.g.
$ sudo apt-get install pylint3  # Note: Only needs to be installed/run once.
$ cd git/IRremoteESP8266
$ pylint3 -d F0001 {src,test,tools}/*.py

Have you added a new ir_*.cpp etc file?

$ cd test
$ make run_tests
$ cd ../tools
$ make run_tests

Merging your Pull Request

To reduce useless noise in the commit log, please use Squash and Merge option to reduce your PR into a single commit before it is merged into the main code branch.

New version release checklist

  1. Make sure your master branch is up-to-date.
    • Warning: The following will cause any local changes to be lost.
    git fetch origin
git checkout master
git reset --hard origin/master
git clean -f -d
  2. git checkout -b vXX.YY.ZZ Where vXX.YY.ZZ is the new version string. e.g. v2.3.2
  3. Update/Re-generate the Doxygen API documentation pages.
    1. Install doxygen if you haven't already.
    2. In the root of the project, run the commands: 
      rm -rf docs/doxygen/html
doxygen
      • If there is no output from the command, all went well! Huzzah.
      • If there are errors or warnings, fix/address them (in the normal PR manor) before proceeding.
    3. Perform the following commands: 
      git add docs/doxygen/html
git commit -m "Regenerate Doxygen documentation for new release"
  4. Change the library version in the code:
    1. Update _IRREMOTEESP8266_VERSION_(MAJOR|MINOR|PATCH) in src/IRremoteESP8266.h to the new version number.
    2. Update version in library.json & version= in library.properties accordingly.
    3. All three must be the same.
  5. Update the version information in the documentation:
    1. Update "Now Available" sections in README.md & README_??.md.
    2. Update ReleaseNotes.md and add a new section for the new release.
      • git log should show you the change history.
      • Update the date to today's date for the new release.
  6. Run tools/mkkeywords > keywords.txt from the top directory. (Requires a Linux machine etc)
  7. Run tools/scrape_supported_devices.py from the top directory. (Requires Python3)
  8. git diff and review the changes are what you expect.
  9. git commit -a and create an appropriate entry. e.g. "v2.3.2 release"
  10. git push --set-upstream origin vXX.YY.ZZ
  11. Wait for the GitHub Actions to complete successfully.
  12. Create a Pull Request to the 'master' branch:
    • Set appropriate reviewers as needed.
    • Copy in the new section of the ReleaseNotes.md as the PR comment.
  13. Wait for:
    1. Approval (or not, all the substantial commits should have already been done)
    2. GitHub Actions to pass
    3. Only then, merge to master.
  14. Go to the Releases tab in github.
    1. Click "Draft a new release".
    2. Tag Version: vXX.YY.ZZ
    3. Target: Master
    4. Release title: IRremoteESP8266 vXX.YY.ZZ
    5. Notes: Cut & paste from the ReleaseNotes.md update.
    6. Make sure the pre-release checkbox is un-checked.
    7. Click the Preview tab and check it looks okay.
    8. Publish Release
  15. The new release is now live. Arduino IDE's Library Manager should pick up the new version within 24 hours.
  16. Publish the documentation (e.g. API docs) to Github Pages.
  17. Update any reported bugs that were fixed by changes that happened between this new version and the now previous one.
  18. Relax. Grab a cold beverage. It's all done.
Clone this wiki locally