CONTRIBUTING.md

@@ -1,56 +1,129 @@
-# Contributing to Rustlings
+## Contributing to Rustlings
 
-First off, thanks for taking the time to contribute! ❤️
+First off, thanks for taking the time to contribute!! ❤️
 
-## Quick Reference
+### Quick Reference
 
-I want to …
+I want to...
 
-- _report a bug!_ ➡️ [open an issue](#issues)
+_add an exercise! ➡️ [read this](#addex) and then [open a Pull Request](#prs)_
-- _fix a bug!_ ➡️ [open a pull request](#pull-requests)
-- _implement a new feature!_ ➡️ [open an issue to discuss it first, then a pull request](#issues)
-- _add an exercise!_ ➡️ [read this](#adding-an-exercise)
-- _update an outdated exercise!_ ➡️ [open a pull request](#pull-requests)
 
-## Issues
+_update an outdated exercise! ➡️ [open a Pull Request](#prs)_
+
+_report a bug! ➡️ [open an Issue](#issues)_
+
+_fix a bug! ➡️ [open a Pull Request](#prs)_
+
+_implement a new feature! ➡️ [open an Issue to discuss it first, then a Pull Request](#issues)_
+
+<a name="#src"></a>
+### Working on the source code
+
+`rustlings` is basically a glorified `rustc` wrapper. Therefore the source code
+isn't really that complicated since the bulk of the work is done by `rustc`.
+
+<a name="addex"></a>
+### Adding an exercise
+
+The first step is to add the exercise! Name the file `exercises/yourTopic/yourTopicN.rs`, make sure to
+put in some helpful links, and link to sections of the book in `exercises/yourTopic/README.md`.
+
+Next make sure it runs with `rustlings`. The exercise metadata is stored in `info.toml`, under the `exercises` array. The order of the `exercises` array determines the order the exercises are run by `rustlings verify` and `rustlings watch`.
+
+Add the metadata for your exercise in the correct order in the `exercises` array. If you are unsure of the correct ordering, add it at the bottom and ask in your pull request. The exercise metadata should contain the following:
+```diff
+  ...
++ [[exercises]]
++ name = "yourTopicN"
++ path = "exercises/yourTopic/yourTopicN.rs"
++ mode = "compile"
++ hint = """
++ Some kind of useful hint for your exercise."""
+  ...
+```
+
+The `mode` attribute decides whether Rustlings will only compile your exercise, or compile and test it. If you have tests to verify in your exercise, choose `test`, otherwise `compile`. If you're working on a Clippy exercise, use `mode = "clippy"`.
+
+That's all! Feel free to put up a pull request.
+
+<a name="issues"></a>
+### Issues
 
 You can open an issue [here](https://github.com/rust-lang/rustlings/issues/new).
 If you're reporting a bug, please include the output of the following commands:
 
-- `cargo --version`
+- `rustc --version`
 - `rustlings --version`
 - `ls -la`
 - Your OS name and version
 
-## Pull Requests
+<a name="prs"></a>
+### Pull Requests
 
-You are welcome to open a pull request, but unless it is small and trivial, **please open an issue to discuss your idea first** 🙏🏼
+Opening a pull request is as easy as forking the repository and committing your
+changes. There's a couple of things to watch out for:
 
-Opening a pull request is as easy as forking the repository and committing your changes.
+#### Write correct commit messages
-If you need any help with it or face any Git related problems, don't hesitate to ask for help 🤗
 
-It may take time to review your pull request.
+We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
-Please be patient 😇
+specification.
+This means that you have to format your commit messages in a specific way. Say
+you're working on adding a new exercise called `foobar1.rs`. You could write
+the following commit message:
 
-## Adding An Exercise
+```
-
+feat: add foobar1.rs exercise
-- Name the file `exercises/yourTopic/yourTopicN.rs`.
-- Make sure to put in some helpful links, and link to sections of the book in `exercises/yourTopic/README.md`.
-- Add a (possible) solution at `solutions/yourTopic/yourTopicN.rs` with comments and links explaining it.
-- Add the [metadata for your exercise](#exercise-metadata) in the `info.toml` file.
-- Make sure your exercise runs with `rustlings run yourTopicN`.
-- [Open a pull request](#pull-requests).
-
-### Exercise Metadata
-
-The exercise metadata should contain the following:
-
-```toml
-[[exercises]]
-name = "yourTopicN"
-dir = "yourTopic"
-hint = """A useful (multi-line) hint for your exercise."""
 ```
 
-If your exercise doesn't contain any test, add `test = false` to the exercise metadata.
+If you're just fixing a bug, please use the `fix` type:
-But adding tests is recommended.
+
+```
+fix(verify): make sure verify doesn't self-destruct
+```
+
+The scope within the brackets is optional, but should be any of these:
+
+- `installation` (for the installation script)
+- `cli` (for general CLI changes)
+- `verify` (for the verification source file)
+- `watch` (for the watch functionality source)
+- `run` (for the run functionality source)
+- `EXERCISENAME` (if you're changing a specific exercise, or set of exercises,
+  substitute them here)
+
+When the commit also happens to close an existing issue, link it in the message
+body:
+
+```
+fix: update foobar
+
+closes #101029908
+```
+
+If you're doing simple changes, like updating a book link, use `chore`:
+
+```
+chore: update exercise1.rs book link
+```
+
+If you're updating documentation, use `docs`:
+
+```
+docs: add more information to Readme
+```
+
+If, and only if, you're absolutely sure you want to make a breaking change
+(please discuss this beforehand!), add an exclamation mark to the type and
+explain the breaking change in the message body:
+
+```
+fix!: completely change verification
+
+BREAKING CHANGE: This has to be done because lorem ipsum dolor
+```
+
+#### Pull Request Workflow
+
+Once you open a Pull Request, it may be reviewed or labeled (or both) until
+the maintainers accept your change. Please be patient, it may take some time
+for this to happen!

README.md

@@ -21,12 +21,9 @@ Before installing Rustlings, you need to have _Rust installed_.
 Visit [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) for further instructions on installing Rust.
 This'll also install _Cargo_, Rust's package/project manager.
 
-> 🐧 If you're on Linux, make sure you've installed `gcc` (for a linker).
+🐧 If you're on Linux, make sure you've installed `gcc` (for a linker). Deb: `sudo apt install build-essential gcc`. Dnf: `sudo dnf install gcc`.
->
-> Deb: `sudo apt install gcc`.
-> Dnf: `sudo dnf install gcc`.
 
-> 🍎 If you're on MacOS, make sure you've installed Xcode and its developer tools by running `xcode-select --install`.
+🍎 If you're on MacOS, make sure you've installed Xcode and its developer tools by typing `xcode-select --install`.
 
 ### Installing Rustlings
 
@@ -35,20 +32,9 @@ The following command will download and compile Rustlings:
 <!-- TODO: Remove @6.0.0-beta.x -->
 
 ```bash
-cargo install rustlings@6.0.0-beta.3
+cargo install rustlings@6.0.0-beta.3 --locked
 ```
 
-<details>
-<summary><strong>If the installation fails…</strong> (<em>click to expand</em>)</summary>
-
-<!-- TODO: Remove @6.0.0-beta.x -->
-
-- Make sure you have the latest Rust version by running `rustup update`
-- Try adding the `--locked` flag: `cargo install rustlings@6.0.0-beta.3 --locked`
-- Otherwise, please [report the issue](https://github.com/rust-lang/rustlings/issues/new)
-
-</details>
-
 ### Initialization
 
 After installing Rustlings, run the following command to initialize the `rustlings/` directory:
@@ -57,7 +43,7 @@ After installing Rustlings, run the following command to initialize the `rustlin
 rustlings init
 ```
 
-Now, go into the newly initialized directory and launch Rustlings for further instructions on getting started with the exercises:
+Now, go into the newly initialized directory and run Rustlings for further instructions on getting started with the exercises:
 
 ```bash
 cd rustlings/
@@ -66,40 +52,45 @@ rustlings
 
 ## Doing exercises
 
-The exercises are sorted by topic and can be found in the subdirectory `exercises/<topic>`.
+The exercises are sorted by topic and can be found in the subdirectory `rustlings/exercises/<topic>`.
-For every topic, there is an additional `README.md` file with some resources to get you started on the topic.
+For every topic there is an additional README file with some resources to get you started on the topic.
-We highly recommend that you have a look at them before you start 📚️
+We really recommend that you have a look at them before you start.
 
+The task is simple.
 Most exercises contain an error that keeps them from compiling, and it's up to you to fix it!
-Some exercises contain tests that need to pass for the exercise to be done ✅
+Some exercises are also run as tests, but Rustlings handles them all the same.
+To run the exercises in the recommended order, execute:
 
-### Watch Mode
+```bash
+rustlings
+```
 
-After [initialization](#initialization), Rustlings can be launched by simply running the command `rustlings`.
+This will try to verify the completion of every exercise in a predetermined order (what we think is best for newcomers).
+It will also rerun automatically every time you change a file in the `exercises/` directory.
 
-This will start the _watch mode_ which walks you through the exercises in a predefined order (what we think is best for newcomers).
+In case you want to go by your own order, or want to only verify a single exercise, you can run:
-It will rerun the current exercise automatically every time you change the exercise's file in the `exercises/` directory.
 
-<details>
+```bash
-<summary><strong>If detecting file changes in the <code>exercises/</code> directory fails…</strong> (<em>click to expand</em>)</summary>
+rustlings run EXERCISE_NAME
+```
 
-> You can add the **`--manual-run`** flag (`rustlings --manual-run`) to manually rerun the current exercise by entering `r` or `run` in the watch mode.
+Or simply use the following command to run the next pending exercise in the course:
->
-> Please [report the issue](https://github.com/rust-lang/rustlings/issues/new) with some information about your operating system and whether you run Rustlings in a container or virtual machine (e.g. WSL).
 
-</details>
+```bash
+rustlings run
+```
 
-### Exercise List
+In case you get stuck, you can run the following command to get a hint for your exercise:
 
-In the [watch mode](#watch-mode) (after launching `rustlings`), you can enter `l` or `list` to open the interactive exercise list.
+```bash
+rustlings hint EXERCISE_NAME
+```
 
-The list allows you to…
+You can also get the hint for the next pending exercise with the following command:
 
-- See the status of all exercises (done or pending)
+```bash
-- `c`: Continue at another exercise (temporarily skip some exercises or go back to a previous one)
+rustlings hint
-- `r`: Reset status and file of an exercise (you need to _reload/reopen_ its file in your editor afterwards)
+```
-
-See the footer of the list for all possible keys.
 
 ## Continuing On
 
@@ -110,15 +101,25 @@ Continue practicing your Rust skills by building your own projects, contributing
 
 ## Uninstalling Rustlings
 
-If you want to remove Rustlings from your system, run the following command:
+If you want to remove Rustlings from your system, there are two steps.
+
+1️⃣ Remove the `rustlings` directory that was created by `rustlings init`:
+
+```bash
+rm -r rustlings
+```
+
+2️⃣ Run `cargo uninstall` to remove the `rustlings` binary:
 
 ```bash
 cargo uninstall rustlings
 ```
 
+That's it!
+
 ## Contributing
 
-See [CONTRIBUTING.md](https://github.com/rust-lang/rustlings/blob/main/CONTRIBUTING.md) 🔗
+See [CONTRIBUTING.md](https://github.com/rust-lang/rustlings/blob/main/CONTRIBUTING.md).
 
 ## Contributors ✨