rust-rustlings-2024-autumn-haiwanwang/CONTRIBUTING.md

Contributing to Rustlings

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

Quick Reference

I want to...

add an exercise! ➡️ read this and then open a Pull Request

update an outdated exercise! ➡️ open a Pull Request

report a bug! ➡️ open an Issue

fix a bug! ➡️ open a Pull Request

implement a new feature! ➡️ open an Issue to discuss it first, then a Pull Request

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 argh CLI that connects to most of the other source files.

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:

  ...
+ [[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.

Issues

You can open an issue here. 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

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 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:

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. Please be patient, it may take some time for this to happen!