CONTRIBUTING.md

Contributing to rovr

First off, thank you for considering contributing to rovr! It's people like you that make rovr such a great tool.

Where do I go from here?

If you've noticed a bug or have a feature request, make one! It's generally best to check if one already exists before making a new one.

Fork & create a branch

If you've decided to contribute, you'll want to fork the repository and create a new branch.

git clone https://github.com/<your-username>/rovr.git
cd rovr
git checkout -b my-new-feature

Development

rovr uses uv for dependency management and poe-the-poet for task management. Preferably install poe globally

uv tool install poethepoet

To set up the development environment, run:

uv sync --dev

uv handles virtual environments for you, but if necessary, activate it by running:

source .venv/bin/activate

(On Windows, you might need to run .venv\Scripts\activate)

poe-the-poet is used for task management. i highly recommend installing poe globally via uv

uv tool install poethepoet

Code Style and Linting

We use ruff for formatting and linting. Before committing, please run:

ruff format

We also use ty for type checking.

ty check

Testing

We use pytest for testing. To run the tests, execute:

poe test

Committing your changes

We follow the Conventional Commits specification. To help with this, you can use commitizen, which is included as a dev dependency. Run uv run cz c to create a commit with commitizen.

Making a Pull Request

When you're ready to make a pull request, please ensure you add the following template to your PR description:

<!--describe your pull request-->

<!--also include videos, screenshots or gifs if applicable if it is a new feature-->

---

by submitting this pull request, i agree that

- [ ] i have run `poe check` to check for any style issues and fixed them
- [ ] i have tested rovr (and also ran `poe test` if applicable) to make sure my changes do not break anything
- [ ] cache, logs, dotfiles and/or others were not accidentally added to git's tracking history
- [ ] my commits (or at least the pr title) follow the conventional commits format as much as possible
- [ ] i did not use an AI (or LLM) in any way to write code.

If your PR is addressing an issue, please link it in the PR description (e.g., "Fixes #123").

Types of Contributions

Bug Fixes

If you are fixing a bug, please create an issue first if one does not already exist. This helps to track the bug and the fix.

Feature Additions

New features are welcome!

Theme Additions

If you've created a cool theme for rovr, we'd love to see it! Please make a pull request with your theme, base tcss (take a look at existing styles for a guide). Don't forget to include screenshots as described in the documentation.

Thank you for your contribution!

Commit Convention

Follow Conventional Commits:

Types: feat, fix, docs, style, refactor, test, chore

For help with this, you can use commitzen by uvx --from commitzen cz c to create a commit with commitizen.

Code preferences

Integrate with the least amount of code possible.

• If you can use stdlib instead of a custom function, do it.
• If refactoring a function allows it to be reusable, do it.

Always run poe check before committing. Ruff may mention that certain errors are fixable; if so, run poe fmt to apply fixes. poe test allows you to run tests in paralel, keep in mind that the tests can be quite flaky at times. If an error occurs, just try again until it passes or 5 tries have been made. If it still fails after 5 tries, then there may be an actual issue that needs to be looked into.

Avoid if TYPE_CHECKING blocks for imports; it looks bad

Do not make direct changes to src/rovr/classes/config.pyi or docs/src/content/docs/dev/reference/schema.mdx, they are auto-generated by poe typed and poe gen-schema.

If adding new icons, ensure they are checked with poe icon-test.

multiprocessing.ProcessPoolExecutor and multiprocessing.Process notices

Avoid importing ProcessPoolExecutor or Process in the same file as rovr.variables.constants imports.

• This is because rovr.variables.constants loads the config, creating a new Process will also automatically load the config, causing stdout corruption when the config is broken

Additionally, ensure that ValueError exceptions are properly handled when creating new Processes, refer to src/rovr/core/preview_container.py's show_image_preview method for an example of handling it.

Interesting Textual Patterns

• event handlers (on_<event>) do not need to call their super() method. Textual implicitly handles this for you. If you don't want it to bubble to the super() method, call prevent_default() on the event.
  • reactive watchers (watch_<var>) on the other hand do need to call their super() method, else the watcher in the super class will not be called

AI policy

_{Adapted from the Mycelium AI Policy source}

when contributing to rovr you are free to use any tools you deem appropriate. this includes the LLM of your choosing, agents, loops, gastown, AI code review tools, Amazon Rufus, or even vim. however, all contributions to this project (including my own) must abide by exactly one rule:

your code (and any associated prose, such as commit messages and documentation) must not look like it was written by a large language model.

basically, the game is simple: contributors are free to use whatever AI tools they wish when contributing to rovr and associated projects, but in order to have your PRs merged, you must be able to trick me into believing it was written by a human being. any PRs which appear to have been generated by a model will be closed as a violation of rovr's AI Policy (even if they were actually written on pencil and paper by a human being in a cave with no access to the internet). repeated violations of the rovr AI Policy may result in a ban from contributing to the repo.

advice on AI policy compliance

• when using an AI coding agent, the easiest way to ensure your contributions are compliant with the rovr AI Policy is to read the code that the model generates, and rewrite any parts of it that "feels like Claude-babble" (if you use codex, congrats, you don't face this issue). repeat this process as needed until it no longer feels like it was written by a model.
• you may feel that it is possible to prompt an LLM into outputting code that doesn't look model-generated. my personal experience has been that this is impossible, and model-written code always requires some degree of rewriting to make it look Normal. if you think you're better at prompting than me, you are welcome to try it, but...good luck!
• while contributors are free to disclose the use of AI tools in their pull requests, note that this will put you at a substantial disadvantage, because an AI disclosure will mean I go in suspicious. if you can trick me into believing that a pull request which says "This code was written using Claude" was written entirely by an organic, free-range human being...well, I'll be impressed.

rationale

this may seem like a weird policy, you would expect a binary outcome from such a policy: either allow AI, or disallow them, why the twist? why do i want contributors to gaslight me into believing their code was written by a human?

1. this project is for fun. i never intended it to reach the heights of yazi, nnn or superfile; if it does, thats great, but the main reason for this project is to satisfy myself, i needed a terminal file manager that was easy to configure, easy to get used to, and easy to use. i wanted to make a file manager that i could enjoy using, and i could make modifications to suit my needs better. it is something i made for myself, and for others to consider using.
2. AI can be useful. i've used many AI tools in the past, they've been of great help to me, to handling unknown APIs and very new APIs. Heck, some of the dependencies of this project are partially written with AI (see textual-drivers and multiarchive). AI can be useful in reviewing, that's why I have it enabled in PRs: it is remarkably thorough in its findings and can point at places that I may overlook. I don't want to restrict that, but I also don't want to be forced to use it. I want to be able to use it when I want, and not when I don't.
3. i can just do whatever the hell i want, what will you do about it?