rustlings/CONTRIBUTING.md

## Contributing to Rustlings

First off, thanks for taking the time to contribute!! ❤️

### Quick Reference

I want to...

_add an exercise! ➡️ [read this](#addex) and then [open a Pull Request](#prs)_

_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`.
`src/main.rs` contains a simple `clap` CLI that loads from `src/verify.rs` and `src/run.rs`.

<a name="addex"></a>
### Adding an exercise

First step is to add the exercise! Call it `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 you want to make sure it runs when using `rustlings`. All exercises are stored in `info.toml`, under the `exercises` array. They're ordered by the order they're ran when using `rustlings verify`.

You want to make sure where in the file you add your exercise. If you're not sure, add it at the bottom and ask in your pull request. To add an exercise, edit the file like this:
```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`.

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:

- `rustc --version`
- `rustlings --version`
- `ls -la`
- Your OS name and version

<a name="prs"></a>
### Pull Requests

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:

#### Write correct commit messages

We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.4/)
specification, because it makes it easier to generate changelogs automatically.
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:

```
feat: Add foobar1.rs exercise
```

If you're just fixing a bug, please use the `fix` type:

```
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. Then, [bors](https://github.com/bors) will
run the test suite with your changes and if it's successful, automatically
merge it in!