Contributing

aarshi is a small project, and every useful report, idea or fix helps. This page explains where to talk about aarshi, what makes a good issue, and how to propose a change.

Report a bug or ask for a feature

Open an issue on the GitHub repository. Choose the bug report or feature request template; if neither fits, open a blank issue. In every case, give enough detail for someone else to reproduce the problem.

A good issue answers these questions:

1. What command did you run? Copy it exactly, flags included, for example aarshi add -s team about.
2. Which version and system? The output of aarshi --version, and your operating system.
3. What did you expect, and what happened? Paste the full output of the command, not a summary of it.
4. Is it about a project? Add the output of aarshi status --json run inside that project. Remove anything private first, such as a site URL you do not want to share.

Give the issue a short title that names the command or the screen concerned, for example add -p: page created without a sitemap entry.

Suggest a feature

Describe the problem before the solution. What were you trying to do, and what did it cost you to do it by hand? A proposed command or flag is welcome, but the problem is what decides whether it is accepted.

Find something to work on

• Documentation. A sentence that is unclear, a missing example, a typo. Every page exists in English and French: fix both, or say in the issue that you can only do one.
• A status rule. A new check needs three things: a rule name in the right subject, an entry in CONVENTIONS.md and CONVENTIONS.fr.md, and a test in tests/cli.rs.
• A bug. Any issue labelled as a bug is a good first pick, once you can reproduce it.

Propose a change

1. Start from the latest code, on a branch with a clear name, for example fix/add-section-prompt.
2. Make the change and add or update a test for it.
3. Run the checks before you push:

   cargo fmt
   cargo clippy --all-targets
   cargo test

4. Open a pull request. Say what changed and why, in a few sentences, and link the issue it answers.

Commit messages

Each commit message starts with a type and a scope, then a short summary:

fix(status): exit 2 when aarshi.toml cannot be analyzed
docs(commands): explain aarshi add step by step

The types you will meet most are feat, fix, docs, refactor and test.

Rules that apply to every change

Languages

Code and comments are in English. The CLI prints in English. The documentation (README, CONTRIBUTING, CONVENTIONS and these pages) is written in English and French, and both versions change together.

Comments

Short, and only where the behaviour is not obvious from the code. Public Rust functions have a /// doc comment.

Design decisions

A change of behaviour is easier to review when its issue or pull request explains the decision it follows from.