Skip to content

Contribute to madbot

Thank you for taking the time to contribute. Every contribution is welcome: a question, a bug report, an idea, a fix in the documentation or in the code.

Everyone taking part in the project follows the code of conduct.

  1. Search the existing issues: someone may have asked the same question. If an issue answers it only partly, ask in that issue.
  2. Otherwise, open an issue and give as much context as you can: what you were trying to do, what happened, and the versions involved (madbot, browser, operating system).

A good bug report lets someone else reproduce the problem without asking you more questions. Before you write it:

  • check that you use the latest version of madbot;
  • check that the problem does not come from your own setup, such as an incompatible version of a dependency;
  • search the open bugs to see if it is already known;
  • collect what describes the problem: the error message or traceback, your operating system and platform, the versions of the tools involved, the input and the output.

Then open an issue with the Bug template:

  • describe what you expected and what happened instead;
  • list the steps that reproduce the problem, as short as possible;
  • add the information you collected.

Before you suggest a new feature or a change to an existing one:

  • check that you use the latest version of madbot, and that this documentation does not already cover it;
  • search the issues of the madbot group: if someone already suggested it, add your use case in a comment;
  • think about who would use it. madbot aims at features that serve most of its users; a connection to one specific system may fit better in a plugin.

Then open an issue with the Suggestion template:

  • give it a clear and descriptive title;
  • describe the improvement step by step;
  • describe the current behaviour, the behaviour you expect instead, and why;
  • add screenshots if they help;
  • explain who would benefit from it.

The code and this documentation live in the madbot repository.

  1. Set up a development environment.
  2. Create a branch and make your change, following the branch and commit conventions.
  3. Run the tests and quality checks, and add or update the tests of your change.
  4. Update the documentation when your change is visible to users, people who run an instance, plugin developers or API users: see Write documentation.
  5. Open a merge request with a description that explains the context and the reason for the change.

You may use an AI assistant to contribute, as the team does. The AI policy of the repository gives the rules; in short:

  • you have read, understood and tested everything you submit, and you can explain it during the review;
  • your merge request goes through the same tests, quality checks and review as any other, and a member of the team reviews and approves it: an AI review can help the reviewer, it never replaces them;
  • your commits carry your own name and email: an AI assistant is never the author or the co-author of a commit;
  • a commit made with the help of an AI assistant ends with an Assisted-by: AI line (see Commit messages), and so does the description of a merge request that contains such commits;
  • you never share secrets, personal data or the content of an instance with an AI tool, and you only use the tools your institution allows.

The AGENTS.md file at the root of the repository gives the same rules, the commit conventions and the checks to run to the AI assistant you work with.

By contributing, you confirm that you are the author of the content you submit and answer for all of it, including the parts written with the help of an AI assistant, that you have the rights to it, and that it can be distributed under the project licence.