diff --git a/HACKING.md b/HACKING.md index 14b18bd1..ba5f71f9 100644 --- a/HACKING.md +++ b/HACKING.md @@ -25,7 +25,7 @@ sudo apt-get -y build-dep . ``` For an explicit list of dependencies check the `Build-Depends` entry in the -[debian/control][] file. +[`debian/control`](./debian/control) file. Testing ------- @@ -62,6 +62,24 @@ $ gsettings set org.gnome.desktop.input-sources sources "[('xkb', 'us'), ('xkb', Coding ------ +### Project structure + +Rust modules should be split into 2 categories: libraries, and user interface. They differ in the way they do error handling. + +Libraries should: + +- not panic due to external surprises, only due to internal inconsistencies +- pass errors and surprises they can't handle to the callers instead +- not silence errors and surprises + +User interface modules should: + +- try to provide safe values whenever they encounter an error +- do the logging +- give libraries the ability to report errors and surprises (e.g. via giving them loggers) + +### Style + Code submitted should roughly match the style of surrounding code. Things that will *not* be accepted are ones that often lead to errors: - skipping brackets `{}` after every `if()`, `else`, and similar @@ -122,6 +140,8 @@ sh /source_path/cargo.sh test ### Cargo dependencies +All Cargo dependencies must be selected in the version available in PureOS, and added to the file `debian/control`. Please check with https://software.pureos.net/search_pkg?term=librust . + Dependencies must be specified in `Cargo.toml` with 2 numbers: "major.minor". Since bugfix version number is meant to not affect the interface, this allows for safe updates. `Cargo.lock` is used for remembering the revisions of all Rust dependencies. It should be updated often, preferably with each bugfix revision, and in a commit on its own: