Development¶
This chapter will get you started with MultiGeiger development.
MultiGeiger is written in C using Arduino-ESP32.
Contributions¶
… are welcome!
Some guidance for contributors:
- discuss about changes on github issue tracker
- make your PRs against the
master
branch - do clean changesets:
- focus on some topic, resist changing anything else.
- do not do style changes mixed with functional changes.
- run the automatic code formatter before committing
- try to avoid refactorings mixed with functional changes.
- if you need to fix something after commit/push:
- if there are ongoing reviews: do a fixup commit you can merge into the bad commit later.
- if there are no ongoing reviews or you did not push the bad commit yet: edit the commit to include your fix or merge the fixup commit before pushing.
- have a nice, clear, typo-free commit comment
- if you fixed an issue, refer to it in your commit comment
- make a pull request on github and check on the PR page what the CI system tells about the code in your PR
- wait for review by other developers
Building a development environment¶
TODO
Automatic Code Formatter¶
We use astyle for automated code formatting / formatting checks.
Run it like this:
astyle --options=.astylerc 'multigeiger/\*'
Documentation¶
Building the docs with Sphinx¶
Documentation is written in English and translated to other languages from that source (initially German).
The documentation (in reStructuredText format, .rst) is in docs/source/
,
index.rst
is the starting point there.
To build the docs, you need to have Sphinx installed and run:
cd docs/
make html
Then point a web browser at docs/build/html/index.html
.
The website is updated automatically by ReadTheDocs through GitHub web hooks on the main repository.
After changes of the (english) master docs, the translation master files (*.pot
)
need updating (adding/removing/updating strings in there):
cd docs/build/gettext
sphinx-build -b gettext ../../source .
Then, these changes need to get pushed to transifex, so translators can comfortably translate on the web:
Translation is organised via [transifex](https://www.transifex.com/thomaswaldmann/multigeiger/), you need to have an account or at least login there and fire a “join team” request. Then translate the missing parts and notify the developers (e.g. via issue tracker).
tx push --source
Later, after translators did their part, updated translations need to get pulled from transifex:
tx pull --all --force
Now we have changes in our git workdir and we need to commit them:
git add locales/
git commit -m "updated translations"
git push
This will trigger a build of the docs and their translation(s) on readthedocs.io.
Flashing devices / creating binaries¶
Arduino IDE:
do a git checkout of the wanted release, e.g.
git checkout V1.13.0
use the default userdefines.h (available as userdefines-example.h)
IDE settings:
- Device: Heltec WiFi Stick (always use this, even if you have a WiFi Kit 32)
- Flash size: 4MB (32Mb)
- Partition scheme: minimal SPIFFS (large APPS with OTA) - this fits onto 4MB devices.
Arduino IDE -> Sketch -> Upload
This is to test whether the compiled code actually works after USB-flashing to your device.
Arduino IDE -> Sketch -> Export compiled binary
This creates a .bin file for OTA updating. Test whether OTA updating using that file works.
Creating a new release¶
Checklist:
- make sure all issues for this milestone are closed or moved to the next milestone
- check if there are any pending fixes for severe issues
- check whether some CA certificate (see
ca_certs.h
) will expire soon and whether we already can add their next valid cert. - find and fix any low hanging fruit left on the issue tracker
- close release milestone on Github
- update
docs/source/changes.rst
, based ongit log $PREVIOUS_RELEASE..
bump2version --new-version 1.23.0 release
- this will:- update versions everywhere
- auto-create a git tag
- auto-create a git commit
- review the automatically generated changeset
- create a github release for this tag:
- create a binary (see above) and attach to the github release
- add a link to the relevant
changes.rst
section to the github release
bump2version --no-tag --current-version 1.23.0 minor
- this will:- update versions everywhere (now to: 1.24.0-dev)
- not quite correctly update changes.rst, will need manual fixing afterwards
- after fixing: git commit –amend