From f6ea1012c6039ad33e2fdc04a6733084da3236d5 Mon Sep 17 00:00:00 2001 From: Federico Ponzi Date: Sun, 3 Nov 2024 10:04:59 +0000 Subject: [PATCH] Update Contributing info --- CONTRIBUTING.md | 63 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f5d88e2..43d92d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,54 +1,74 @@ # Contributing to Horust -Thanks for considering contributing to Horust! -[Github Issue](https://github.com/FedericoPonzi/horust/issues) are a good place for getting started. +Thanks for considering contributing to Horust! + +[GitHub Issues](https://github.com/FedericoPonzi/horust/issues) are a good place for getting started. You can also search the code for `TODO`s. -We should use [issues](https://github.com/FedericoPonzi/Horust/issues/new) to track things to do. Thus every PR should fix one or more issues. -So even if you want to fix a TODO, please create an issue first. -In this way it's easier to keep track of who's working on what. +We should use [issues](https://github.com/FedericoPonzi/Horust/issues/new) to track things to do. Thus, every PR should +fix one or more issues. +So even if you want to fix a TODO, please create an issue first. +In this way, it's easier to keep track of whom's working on what. If you need any help on clarifying the acceptance +criteria of an issue or work on the task, please do rech out. ## Development environment -In order to start hacking on Horust, you will need to install [Rust](https://www.rust-lang.org/tools/install) (1.42.0). -By using rustup, you will also automatically install cargo and other needed tools. -You can run horust with debug logs by using: +To start hacking on Horust, you will need to install [Rust](https://www.rust-lang.org/tools/install) (>1.42.0) and +protoc, the protobuf compiler (apt-get install protobuf-compiler). +By using rustup, you will also automatically install cargo and other necessary tools. + +You can run horust with debug logs on by using: + ```bash HORUST_LOG=debug cargo run ``` Passing arguments to horust via cargo: + ```bash HORUST_LOG=debug cargo run -- --sample-service ``` Run Horust in single command mode: + ```bash HORUST_LOG=debug cargo run -- -- /bin/bash ``` ## For PRs: + Before almost every commit, you might want to check your fmt: + ``` cargo fmt ``` Clippy for lints: + ``` cargo clippy ``` +Cargo fix can also be used to fix common lint issues: + +``` +cargo fix +``` + And run tests: + ``` cargo test ``` If you want to run integration tests only: + ``` cargo test --package horust --test horust -- --exact ``` -There is also a make file, at the moment used mainly for docker: +There is also a make file, at the moment, used mainly for docker: + ``` # build a container without the http feature: make build-nofeature @@ -67,12 +87,13 @@ If you'd like to skip all the bells and whistles of setting up the project, you and then work off the container instead of compiling locally. The `Makefile` contains a set of commands intended to scaffold an AIO container from scratch. - + Just run `make dargo COMMAND=X`, where `X` is any valid `cargo` command, inside the project's root folder. If this is the first time you run the command, it will: 1. Create a Docker image with a pre-determined working directory -2. Run an (interactive / long-running) container off that image, with the local Horust project folder bind-mounted to the working directory +2. Run an (interactive / long-running) container off that image, with the local Horust project folder bind-mounted to + the working directory 3. Run `cargo X` inside the container When the Makefile target finishes, you will have a running container on your machine that you can compile Horust in. @@ -80,37 +101,45 @@ That container allows you to take advantage of `rustc`'s incremental compilation If it's not the first time you run the command, it will just run `cargo X` inside the container. -If you'd like to go for maximum ergonomics, run the following command (swapping `~/.bashrc` for `~/.zshrc` or wherever you keep your shell stuff): - +If you'd like to go for maximum ergonomics, run the following command (swapping `~/.bashrc` for `~/.zshrc` or wherever +you keep your shell stuff): + ```bash echo 'dargo(){ make dargo COMMAND=$1}' >> ~/.bashrc source ~/.bashrc ``` -This will now enable you to run `dargo X` instead of `make dargo COMMAND=X`, to get a more `cargo`-like feel while using the container. +This will now enable you to run `dargo X` instead of `make dargo COMMAND=X`, to get a more `cargo`-like feel while using +the container. Try running `dargo check` to see how if feels! ### Container-based development example -Just to make sure everything is clear, let's run a step-by-step mini tutorial on developing in container-based workflow "mode": +Just to make sure everything is clear, let's run a step-by-step mini tutorial on developing in container-based +workflow "mode": 1. Clone the repo to your local machine: + ```shell git clone https://github.com/FedericoPonzi/Horust.git` cd Horust ``` + 2. Make some changes to a source file. 3. Run the following to create the AIO container and then test your changes: + ```shell make dargo COMMAND=test ``` ## Useful Links: + Just a small collection of useful links: + * https://www.youtube.com/watch?v=gZqIEstv5lM * https://docs.google.com/presentation/d/1jpAOBDiYfTvK3mWHuzrP8vaK7OUoALNCvegiibuvmYc/edit * http://www.man7.org/linux/man-pages/man7/signal-safety.7.html -* https://github.com/tokio-rs/mio/issues/16 +* https://github.com/tokio-rs/mio/issues/16 * https://github.com/tokio-rs/mio/issues/16#issuecomment-102156238 * https://skarnet.org/software/s6/s6-svscan-1.html * https://felipec.wordpress.com/2013/11/04/init/ @@ -118,6 +147,7 @@ Just a small collection of useful links: * https://blog.darknedgy.net/technology/2015/09/05/0/ ## Random init systems: + * https://github.com/Yelp/dumb-init * https://github.com/fpco/pid1 * https://github.com/krallin/tini/ @@ -125,6 +155,7 @@ Just a small collection of useful links: * https://github.com/OpenRC/openrc/blob/master/supervise-daemon-guide.md ## Useful man pages: + * man runlevel * man 8 init * man getty