velox-bot/CONTRIBUTING.md

Contributing to Velox Bot

Thanks for wanting to help. This page is the short version of how to do it well. The longer technical material is in the Development guide.

Ways to help

• Report a bug. Say what you did, what you expected and what happened. Include the bot's log lines around the problem and whether it happens in more than one server. Never paste a bot token, a database password or a .env file.
• Suggest a feature. Explain the problem it solves for a server, not only the command you imagine.
• Improve the documentation. Wrong or missing docs are bugs. A fix to docs/ is always welcome.
• Fix something or build something. Pick an issue, or open one first (see below).

Security problems

If you find a way to get around a permission check, make the bot act for someone who shouldn't be able to ask, or leak a token, do not open a public issue. Contact the maintainer privately, using the contact details on the repository's profile, and give them time to fix it before you share it.

Before you write code

1. Open an issue for anything big: a new module, a change to how permissions or security work, a change to the database. It saves you from writing something that can't be merged.
2. Read Architecture so you know the layers, and the Development guide for the recipe that matches your change.
3. For anything that touches the database, read Database. A schema change has to keep a bot that is one version behind working for a short while.

Making the change

1. Fork the repository and create a branch from dev: git checkout -b my-change dev. master only holds releases.
2. Keep the change focused. One pull request, one purpose. Unrelated cleanup goes in its own pull request.
3. Follow the code around you: naming, comment density, error handling. Comments explain why, not what.
4. Add tests. At minimum, test the permission check (does the wrong person get refused?), limits, and anything that parses input. See Testing.
5. Update the documentation that your change makes wrong: /help (internal/commands/help/help.go), Command reference and Features.

Before you push:

gofmt -l .                                     # format the files you touched
go build ./... && go vet ./... && go test -race ./...

Some older files are not gofmt-clean. Format the files you change, and leave the rest alone so the diff stays readable.

The rules that matter most

These are the things a reviewer will check first. The reasons are in the Development guide.

• Fail closed. If you can't tell whether someone is allowed, they are not.
• Check permissions in the handler. DefaultMemberPermissions only hides a command from the menu.
• No SQL outside repos. Always use query parameters ($1), never string formatting.
• A module that acts on a server starts off. An admin turns it on.
• Every setting has a command. The bot works fully without a dashboard, so a setting must be visible and changeable with slash commands.
• Escape user text and set AllowedMentions so a message can't ping people.
• Validate everything that comes from users or from other programs writing to the database: options, custom IDs, command payloads.
• No secrets in code, logs, tests or commit messages.

Commit messages and pull requests

• Write the commit subject in the imperative and keep it short ("Add a limit of 10 meeting lobbies"). Use the body to explain why, when it isn't obvious.
• In the pull request, say what changed and why, how you tested it, and whether it needs a database change or a deploy in a particular order.
• Keep the pull request open to review comments. Small follow-up commits are fine, there is no need to squash them yourself.

Behaviour

Be kind and be specific. Disagree with the code, not the person. Harassment, personal attacks and discrimination are not tolerated, and the maintainer may remove comments, close discussions or block people who do it.

License

By contributing, you agree that your contribution is licensed under the Apache License 2.0, the same as the project (section 5 of the license covers this). You keep the copyright on your own work.