Update readme and add changelog

README.md

@@ -14,7 +14,7 @@ Written in [Rust]. See [firmware] folder for details.
 
 ## Contributions
 
-If you like this project, want to use it at your club, or if you want to discuss ideas and suggestions, feel free to start a [discussion][discussions] or open an [issue][issues]. Feel free to fork this repository and base your work upon it. If you implement changes or features that can be useful for everyone, please open a pull request.
+If you like this project, want to use it at your club, or if you want to discuss ideas and suggestions, feel free to start a [discussion][discussions] or open an [issue][issues]. Feel free to fork this repository and base your work upon it. Please open a pull request if your changes or features are useful to a broad audience.
 
 ## License
 
@@ -28,10 +28,9 @@ Unless you explicitly state otherwise, any contribution intentionally submitted
 [discussions]: https://github.com/zargony/touch-n-drink/discussions
 [issues]: https://github.com/zargony/touch-n-drink/issues
 
-[LSC Hamm]: https://flugplatz-hamm.de
-[EDLH]: https://skyvector.com/airport/EDLH/Hamm-Lippewiesen-Airport
-[Rust]: https://rust-lang.org
-
 [Apache License 2.0]: https://opensource.org/license/apache-2-0
 [CERN Open Hardware License Version 2 (Permissive)]: https://opensource.org/license/cern-ohl-p
+[EDLH]: https://skyvector.com/airport/EDLH/Hamm-Lippewiesen-Airport
+[LSC Hamm]: https://flugplatz-hamm.de
 [MIT License]: https://opensource.org/license/mit
+[Rust]: https://www.rust-lang.org

firmware/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+- First release

firmware/README.md

@@ -4,17 +4,9 @@ Firmware images are automatically build by GitHub actions. They can be downloade
 
 ## Requirements
 
-### Rust Toolchain
+For local development, you need a [Rust] toolchain. If your OS doesn't already provide it, easiest way to install and manage Rust toolchains is to use [rustup]. Alternatively, you can run Rust using the official Docker image `rust:1`.
 
-If your OS doesn't provide a Rust compiler, easiest way to install and manage Rust toolchains is to install **rustup** (<https://rustup.rs>). It installs the latest stable Rust toolchain which can later be updated by running `rustup update`.
-
-### espflash
-
-To flash the firmware to a device, the `espflash` tool can be used. It integrates well with the Rust build tools. To install it, run:
-
-```sh
-cargo install espflash cargo-espflash
-```
+To flash the firmware to a device, the `espflash` tool can be used. It integrates well with the Rust build tools and can be installed with `cargo install espflash cargo-espflash`.
 
 ## Building the Firmware
 
@@ -32,6 +24,13 @@ To flash the firmware to a device, connect the device via its USB-C serial port
 cargo espflash flash --release
 ```
 
+## Contributions
+
+If you implement changes or features that can be useful for everyone, please fork this repository and open a pull request. Make sure to also update documentation and code comments accordingly and add a high level description of your changes to the changelog. Also make sure that all CI jobs are passing and ideally try flashing and using the firmware image artifact to verify its behaviour.
+
 [actions]: https://github.com/zargony/touch-n-drink/actions
-[esptool-js]: https://espressif.github.io/esptool-js/
 [releases]: https://github.com/zargony/touch-n-drink/releases
+
+[esptool-js]: https://espressif.github.io/esptool-js
+[Rust]: https://www.rust-lang.org
+[rustup]: https://rustup.rs