chore: updating docs

CONTRIBUTING.md

@@ -70,91 +70,86 @@ Once merged to the main branch, `po` files and any documentation change will be
 
 ### Setup on Ubuntu
 
-```shell
+```bash
 # Install the Rust toolchain
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal
 source "$HOME/.cargo/env"
 
 # Install build-time dependencies
-sudo apt update
-sudo apt install -y git gcc libssl-dev pkg-config protobuf-compiler
+sudo apt-get update
+sudo apt-get install -y git gcc libssl-dev pkg-config protobuf-compiler
 
-# (Optional) Install Docker for running the OCI image
+# Install Docker for running the OCI image and integration tests
+sudo apt-get docker-compose
+sudo usermod -aG docker $USER
+newgrp docker
+
+# Alternatively, if you wish to install docker using the script provided by
+# Docker themselves:
 curl -fsSL https://get.docker.com -o /tmp/get-docker.sh
 sh /tmp/get-docker.sh
-
-# For running the dotenv files
-cargo install dotenvy --features=cli
 ```
 
-### Building and running the binaries
-
-To build and run the binary during development:
-
-```shell
-dotenvy -f .env_files/example.env docker compose up -d #or podman-compose up 
-# Build and run
-dotenvy -f .env_files/example.env cargo run --release
-```
+### Building and running the server
 
-To _just_ build the binary you can run `cargo build --release`. The result will be placed at
-`./target/release/ratings`.
+For local development there is a docker-compose file that can be used to run
+the server alongside a local Postgres database for manual tesing and execution
+of the integration test suite. The `Makefile` in the root of the repo has a
+number of targets for running common actions within the project:
 
-### About the testsuite
+```bash
+# To build the release artifact (located in ./target/release/ratings)
+make build
 
-The project includes a comprehensive testsuite made of unit and integration tests. All the tests must pass before the review is considered. If you have troubles with the testsuite, feel free to mention it on your PR description.
+# To start the local stack:
+make up
 
-Currently (but to be changed) this test suite makes use of `cargo-make` and `docker` to coordinate tests. 
+# To stop the local stack
+make down
 
-To install these dependencies:
+# To run only the unit tests
+make test
 
-```
-# Install cargo-make
-cargo install cargo-make
+# To run only the integration tests (requires the local stack to be up)
+make integration-test
 
-# Install docker
-curl -fsSL https://get.docker.com -o /tmp/get-docker.sh
-sh /tmp/get-docker.sh
+# To run all tests (requires the local stack to be up)
+make test-all
 ```
 
-Tests are located under the `tests/` folder and the coordination scripts are located in the `Makefile.toml` file.
-
-These tests require a database to run against. The easiest way to set up the database, run the tests and clean up is via the following commands:
-
-```
-# Run the tests
-cargo make full-test
+### About the testsuite
 
-# Clean up docker images and build artifacts
-cargo make full-clean
-```
+The project includes a comprehensive testsuite made of unit and integration
+tests. All the tests must pass before the review is considered. If you have
+troubles with the testsuite, feel free to mention it on your PR description.
 
-The test suite must pass before merging the PR to our main branch. Any new feature, change or fix must be covered by corresponding tests.
-Also please note that the `category` suite will take *quite a while* to finish, so be patient with it or skip it by manually running the tests you need with `cargo test --test <your-tests>` if you're not touching the category feature.
+Unit tests are located within the files containing the code they are testing.
 
-Note that the above won't work if you use `podman` (unless you've put in effort to alias docker commands to `podman` and `podman-compose`),
-alternatively you can use:
+Integration tests located in `./tests/` and run against the local docker-compose
+stack (see the [Building and running the server](#building-and-running-the-server)
+section above for details).
 
-```
-dotenvy -f .env_files/test.env podman-compose up
-dotenvy -f .env_files/test-server.env cargo run
-dotenvy -f .env_files/test.env cargo test
-```
+The test suite must pass before merging the PR to our main branch. Any new
+feature, change or fix must be covered by corresponding tests.
 
-In separate tabs (or `tmux` sessions etc), so long as you have the Docker repositories added as a `podman` source.
+For more information on writing Rust tests, the following likes are useful:
+  - <https://doc.rust-lang.org/book/ch11-01-writing-tests.html>
+  - <https://doc.rust-lang.org/rust-by-example/testing/unit_testing.html>
 
 ### Code style
 
 This project follow the [rust style-guide](https://doc.rust-lang.org/1.0.0/style/README.html).
 
 ## Contributor License Agreement
 
-It is required to sign the [Contributor License Agreement](https://ubuntu.com/legal/contributors) in order to contribute to this project.
+It is required to sign the [Contributor License Agreement](https://ubuntu.com/legal/contributors)
+in order to contribute to this project.
 
 An automated test is executed on PRs to check if it has been accepted.
 
 This project is covered by [THIS LICENSE](LICENSE).
 
 ## Getting Help
 
-Join us in the [Ubuntu Community](https://discourse.ubuntu.com/c/desktop/8) and post your question there with a descriptive tag.
+Join us in the [Ubuntu Community](https://discourse.ubuntu.com/c/desktop/8) and
+post your question there with a descriptive tag.

Makefile

@@ -1,3 +1,7 @@
+.PHONY: build
+build:
+	@cargo build --release
+
 .PHONY: up
 up:
 	@docker-compose up

README.md

@@ -12,23 +12,32 @@
 [![License][license-image]](LICENSE)
 <!-- [![Code coverage][codecov-image]][codecov-url] -->
 
-This is the code repository for **Ratings**, the backend service responsible for managing the new vote and rating system used in [App Center](https://github.com/ubuntu/app-center)
+This is the code repository for **Ratings**, the backend service responsible
+for managing the new vote and rating system used in [App Center](https://github.com/ubuntu/app-center)
 
-For general details, including installation, getting started and setting up a development environment, head over to our section on [Contributing to the code](CONTRIBUTING.md#contributing-to-the-code).
+For general details, including installation, getting started and setting up a
+development environment, please see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Dependencies
 
-In order to run, this needs you to install at minimum `libssl-dev` (for OpenSSL) and `protobuf-compiler` (for `prost`) via `apt`.
+In order to run, this needs you to install at minimum `libssl-dev` (for
+OpenSSL) and `protobuf-compiler` (for `prost`) via `apt`.
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ## Get involved
 
-This is an [open source](LICENSE) project and we warmly welcome community contributions, suggestions, and constructive feedback. If you're interested in contributing, please take a look at our [Contribution guidelines](CONTRIBUTING.md) first.
+This is an [open source](LICENSE) project and we warmly welcome community
+contributions, suggestions, and constructive feedback. If you're interested in
+contributing, please take a look at our [Contribution guidelines](CONTRIBUTING.md) first.
 
 - To report an issue, please file a bug report against our repository.
 - For suggestions and constructive feedback, please file a feature request or a bug report.
 
 ## Get in touch
 
-We're friendly! We have a community forum at [https://discourse.ubuntu.com](https://discourse.ubuntu.com) where we discuss feature plans, development news, issues, updates and troubleshooting.
+We're friendly! We have a community forum at [https://discourse.ubuntu.com](https://discourse.ubuntu.com)
+where we discuss feature plans, development news, issues, updates and troubleshooting.
 
-For news and updates, follow the [Ubuntu twitter account](https://twitter.com/ubuntu) and on [Facebook](https://www.facebook.com/ubuntu).
+For news and updates, follow the [Ubuntu twitter account](https://twitter.com/ubuntu)
+and on [Facebook](https://www.facebook.com/ubuntu).