Library Maintainers Guide

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 Travis 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++

• Style guide: Google C++ Style Guide
• Linter: cpplint
• Checks enforced for: *.{h,c,cc,cpp,hpp,ino}

Python

• Style guide: Google Python Style Guide
• Linter: pylint with pylintrc config.
• Automatic code style formatting: yapf with a .style.yapf config. e.g. Google and two-space indents.
• Checks enforced for: *.py

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. Travis 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.

New version release checklist

1. git checkout master; git pull Make sure your master branch is up-to-date
2. git checkout -b vXX.YY.ZZ Where vXX.YY.ZZ is the new version string. e.g. v2.3.2
3. Change the library version in the code:
   1. Update _IRREMOTEESP8266_VERSION_ 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.
4. Update the version information in the documentation:
   1. Update "Now Available" section in 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.
5. Run tools/mkkeywords > keywords.txt from the top directory. (Requires a Linux machine etc)
6. git diff and review the changes are what you expect.
7. git commit -a and create an appropriate entry. e.g. "v2.3.2 release"
8. git push --set-upstream origin vXX.YY.ZZ
9. Wait for the Travis build to complete successfully.
10. 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.
11. Wait for:
    1. Approval (or not, all the substantial commits should have already been done)
    2. Travis to pass
    3. Only then, merge to master.
12. 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
    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
13. The new release is now live. Arduino IDE's Library Manager should pick up the new version within 24 hours.
14. Update any reported bugs that were fixed by changes that happened between this new version and the now previous one.
15. Relax. Grab a cold beverage. It's all done.