doc: Rewrite the readme and add a contributing guide

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing guide
+
+Hello and thank you for your interest in contributing to the Alumet project!
+
+Here is what you need to know.
+
+## The repositories
+
+### Main repository (the one you are in)
+
+This repository is divided in several parts:
+- The `alumet` crate contains the core of the measurement tool, as a Rust library.
+- Binaries can be created from this library, in order to provide a runnable measurement software. The official binaries that we provide are defined in `app-agent`. Agents always depend on `alumet`.
+- Plugins are defined in separate folders: `plugin-nvidia`, `plugin-rapl`, etc. Plugins always depend on `alumet`.
+- Two more crates, `alumet-api-dynamic` and `alumet-api-macros`, ease the creation of dynamic plugins written in Rust. This is WIP (work in progress) = not finished yet.
+- `test-dynamic-plugins` only exists for testing purposes.
+
+### Other repositories
+
+The [`alumet-dev` organization](https://github.com/alumet-dev) contains additional repositories for the website and the packaging of the tool. You'll find more information in each repository.
+
+## What you can do
+
+There are several categories of tasks that can help the Alumet projet. You don't necessarily need to code in Rust!
+
+### Report issues
+
+If you find a bug in the Alumet library or in one of the official agents, you should [open an issue on the `alumet` repository](https://github.com/alumet-dev/alumet/issues). Please use the search function to make sure that the bug you have found has not already been reported. For questions that are not bugs, or if you are not sure whether something is a bug or not, you can [open a discussion](https://github.com/alumet-dev/alumet/discussions).
+
+If you find a mistake or confusing point in the user book or in the developer book, you should open an issue on the `user-book` or `developer-book` repository.
+
+### Write documentation
+
+Writing documentation or tutorials that show how to use Alumet, in the [user book](https://github.com/alumet-dev/user-book), is very helpful to the project
+
+If you have a good understanding of Alumet internals, you can also explain how to write plugins and how to  contribute to Alumet, in the [developer book](https://github.com/alumet-dev/developer-book).
+
+### Code 🧑‍💻
+
+Using the open issues on GitHub, you can find something to work on. You should choose an issue that is not already assigned to someone. If unsure, feel free to ask in a comment or in a new discussion.
+
+If you are an external contributor, it works as follows:
+1. Find something to work on using the [issues](https://github.com/alumet-dev/alumet/issues) or the [discussions](https://github.com/alumet-dev/alumet/discussions).
+2. Fork the alumet repository.
+3. Create a new git branch to work on.
+4. On this branch, implement the fix or feature that you'd like Alumet to have.
+5. Document new functions and types. Write [unit tests](https://doc.rust-lang.org/rust-by-example/testing/unit_testing.html) and/or integration tests. Run the tests with `cargo test`.
+6. Format your code by running `cargo fmt` in the projet directory. We provide a `.rustfmt.toml` that will be automatically used by the formatting tool.
+7. When you are ready, submit your work by opening a [Pull Request (PR)](https://github.com/alumet-dev/alumet/pulls).
+
+If your goal is to optimize somethings, please run benchmarks and provide [flame graphs](https://github.com/killercup/cargo-flamegraph) or other metrics to show your improvements. For micro-benchmarks, we recommend the tool [Criterion](https://bheisler.github.io/criterion.rs/book/index.html).
+
+## Rust good practices
+
+### Linting
+
+You should use [Clippy](https://doc.rust-lang.org/stable/clippy/index.html) to lint your code. The workspace `Cargo.toml` defines some lint rules, that must apply to every crate in the Alumet repository.
+
+Manual action required: if you add a crate (like a plugin) to the repository, add the following two lines to your `Cargo.toml`:
+
+```toml
+[lints]
+workspace = true
+```
+
+### Dependencies
+
+When you add a new plugin to the repository, make it depend on the `alumet` crate in a relative way, without specifying a version. That is, the `dependencies` section of its `Cargo.toml` should look like this:
+
+```toml
+[dependencies]
+alumet = { path = "../alumet" }
+```
+
+### Basic tips
+
+- For efficiency, avoid too much cloning. It's fine for a PoC but should be optimized before merging the PR.
+- Use `anyhow` and `thiserror` to simplify error management. Alumet already uses those.
+- Use [`log`](https://docs.rs/log/latest/log/) to log messages, not `println`. Example:
+```rs
+let value = ();
+log::debug!("My value is: {value:?}");
+```
+
+### Advanced tips
+
+- Alumet internally uses Tokio. To contribute to the core of Alumet, please first follow the [Tokio tutorial](https://tokio.rs/tokio/tutorial). This is not necessary for most plugins.
+- If you get weird errors with `async` code, such as `higher-ranked lifetime error`, try to decompose your operation in several functions and variables, and write down the types of each step explicitly. This will help the compiler to figure out the types of the futures.

README.md

@@ -1,41 +1,55 @@
-# ALUMET
+<p align="center">
+    <img src="readme/alumet-banner.png" height="141px"></img>
+</p>
+
+#
 
 **Adaptive, Lightweight, Unified Metrics.**
 
-ALUMET is a generic measurement tool that brings together research and industry.
-Interesting features include:
-- true modularity: you can add new sources of measurements, data transforms and outputs without modifying the core of the tool
-- pay only for what you need: by choosing the plugins that are included in the tool, you avoid bloat and stay lightweight
-- performance: built in Rust, optimized for low latency and low memory consumption
-- unification: one core, one interface for all your metrics on all your devices
+**ALUMET** is a modular tool that measures energy consumption and performance metrics. It offers a new standard framework for all your measurements, with a very low overhead. [Learn more on the website](https://alumet.dev).
+
+<!-- QUICK DEMO ASCIINEMA HERE -->
+
+## Why should I use it?
 
-Learn more on [the website](https://alumet.dev).
+- [x] I want to estimate the energy consumption of the software I run.
+- [x] I want to measure the energy consumption of my CPU or GPU, _accurately_[^1].
+- [x] I need to export my measurements to local files or to a database.
+- [x] I would like to choose the acquisition frequency and to be able to use frequencies above 1000 Hz. 
+- [x] I _don't_ want the measurement tool to eat up my CPU and consume too much power.
+- [x] I _don't_ want to setup a different tool for each hardware component and software environment I have (laptops, Edge devices with GPUs, bare-metal HPC servers, K8S clusters, ...).
 
-## What can I measure with it?
+If you answer yes to any of these questions, Alumet is for you!
 
-Alumet sources include:
-- RAPL counters on x86 CPUS
-- NVIDIA dedicated GPUs
-- NVIDIA Jetson devices
-- Linux perf_events for processes and cgroups
-- Kubernetes pods (WIP)
+We also have extra features (see the documentation).
 
-If your favorite feature is not listed above, don't worry! The list of plugins is rapidly growing, and we have an ambitious roadmap.
+[^1]: See the following research paper for a detailed analysis of some common errors in RAPL-based measurement tools: [Guillaume Raffin, Denis Trystram. Dissecting the software-based measurement of CPU energy consumption: a comparative analysis. 2024. ⟨hal-04420527v2⟩](https://hal.science/hal-04420527).
 
 ## How to use
 
-Please read [the Alumet user book](https://alumet-dev.github.io/user-book/) to learn how to install and use Alumet.
+Please read [the Alumet user book](https://alumet-dev.github.io/user-book/) to learn how to install and use the Alumet "agent" (the program that performs the measurements).
+
+If you have a question, feel free to ask on the [Discussions page](https://github.com/alumet-dev/alumet/discussions).
+
+## Extending Alumet
 
-## This repository
+The `alumet` crate provides a library with a plugin system. With plugins, you can extend Alumet in the following ways:
+- read new sources of measurements
+- apply arbitrary transformations to the data (such as energy attribution models)
+- export the data to new outputs
+- perform actions on startup and shutdown
 
-ALUMET is divided in several parts:
-- The `alumet` crate contains the core of the measurement tool, as a Rust library.
-- Binaries can be created from this library, in order to provide a runnable measurement software, such as `app-agent`.
-- Plugins are defined in separate folders: `plugin-nvidia`, `plugin-rapl`, etc.
-- Two more crates, `alumet-api-dynamic` and `alumet-api-macros`, ease the creation of dynamic plugins written in Rust (WIP).
-- `test-dynamic-plugins` only exists for testing purposes.
+Please read [the Alumet developer book](https://alumet-dev.github.io/developer-book/) to learn how to make plugins.
+
+## Contributing
+
+Alumet is a joint project between the LIG (computer science laboratory of Grenoble) and Eviden (Atos HPC R&D). It is also open to external volunteers like you!
+
+Please go to the [contributing guide](./CONTRIBUTING.md) to get started.
 
 ## License
 
 Copyright 2024 Guillaume Raffin, BULL SAS, CNRS, INRIA, Grenoble INP-UGA.
 Licensed under the EUPL-1.2 or later.
+
+You can find [more information about the EUPL here](https://joinup.ec.europa.eu/collection/eupl/introduction-eupl-licence). The EUPL is compatible with many other open source licenses and shares some principles with the well-known LGPL.