2019-06-09 08:39:00 -04:00
## Contributing to Rustlings
First off, thanks for taking the time to contribute!! ❤️
### Quick Reference
I want to...
2019-06-09 08:46:38 -04:00
_add an exercise! ➡️ [read this ](#addex ) and then [open a Pull Request ](#prs )_
2019-06-09 08:39:00 -04:00
_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 )_
2019-06-09 08:46:38 -04:00
< 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
2021-02-09 17:43:53 -05:00
The first step is to add the exercise! Name the file `exercises/yourTopic/yourTopicN.rs` , make sure to
2019-06-09 08:46:38 -04:00
put in some helpful links, and link to sections of the book in `exercises/yourTopic/README.md` .
2022-07-15 06:57:54 -04:00
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` .
2019-06-09 08:46:38 -04:00
2021-02-09 17:43:53 -05:00
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:
2019-06-09 08:46:38 -04:00
```diff
...
+ [[exercises]]
2019-11-11 12:02:56 -05:00
+ name = "yourTopicN"
2019-06-09 08:46:38 -04:00
+ path = "exercises/yourTopic/yourTopicN.rs"
+ mode = "compile"
2019-11-11 12:02:56 -05:00
+ hint = """
+ Some kind of useful hint for your exercise."""
2019-06-09 08:46:38 -04:00
...
```
2022-07-15 06:57:54 -04:00
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"` .
2019-06-09 08:46:38 -04:00
That's all! Feel free to put up a pull request.
2019-06-09 08:39:00 -04:00
< 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/ )
2022-07-15 06:57:54 -04:00
specification.
2019-06-09 08:39:00 -04:00
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:
```
2022-07-15 06:57:54 -04:00
feat: add foobar1.rs exercise
2019-06-09 08:39:00 -04:00
```
If you're just fixing a bug, please use the `fix` type:
```
2022-07-15 06:57:54 -04:00
fix(verify): make sure verify doesn't self-destruct
2019-06-09 08:39:00 -04:00
```
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:
```
2022-07-15 06:57:54 -04:00
fix: update foobar
2019-06-09 08:39:00 -04:00
closes #101029908
```
If you're doing simple changes, like updating a book link, use `chore` :
```
2022-07-15 06:57:54 -04:00
chore: update exercise1.rs book link
2019-06-09 08:39:00 -04:00
```
If you're updating documentation, use `docs` :
```
2022-07-15 06:57:54 -04:00
docs: add more information to Readme
2019-06-09 08:39:00 -04:00
```
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:
```
2022-07-15 06:57:54 -04:00
fix!: completely change verification
2019-06-09 08:39:00 -04:00
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
2022-07-15 06:57:54 -04:00
the maintainers accept your change. Please be patient, it may take some time
for this to happen!