Skip to main content

​
Contributing

XDiscordUltimate is open source under the MIT license and welcomes contributions. This guide covers the workflow from fork to pull request, plus the code and security standards every change must meet.

​
Workflow

1

Fork and clone

Fork xreatlabs/XDiscordUltimate on GitHub, then clone your fork.
git clone https://github.com/YOUR_USERNAME/XDiscordUltimate.git
cd XDiscordUltimate
git remote add upstream https://github.com/xreatlabs/XDiscordUltimate.git
2

Create a branch

Branch off main. Use a descriptive name prefixed by type.
git checkout -b feature/broadcast-module
# or: fix/ticket-channel-leak, docs/api-events
3

Write the code

Match the existing package layout and patterns — see Code Standards below. New features should be implemented as a Module under com.xreatlabs.xdiscordultimate.modules.<name>, and every database access must go through DatabaseManager’s async API.
4

Run the tests

./gradlew test
The suite uses JUnit 5 and Mockito. If your change touches persistence, add a test that exercises the new query against the in-memory SQLite test driver.
5

Build the shaded JAR

./gradlew shadowJar
Confirm the build completes and the JAR appears at build/libs/XDiscordUltimate-1.2.0.jar. See Building from Source.
6

Commit with a clear message

Use conventional-commit style summaries so history stays readable.
git add .
git commit -m "feat(modules): add broadcast module with /broadcast slash command"
7

Open a pull request

Push your branch and open a PR against main. Reference any related issue, describe what changed and why, and note how you tested it.
git push origin feature/broadcast-module

​
Code Standards

​
Security Notes

Bot tokens, verification codes, database credentials, and webhook URLs are secrets. Never log them, never include them in exception messages, and never commit them to the repository.
  • No secret logging. The plugin logger and module helpers must never receive a token, code, or password. When logging an error that may carry sensitive context, log only the failure type and a sanitized identifier.
  • Use SecureRandom for any secret — verification codes, tokens, or unguessable identifiers. Plain Random is predictable.
  • Parameterized queries only. DatabaseManager already follows this rule; new SQL must too. Never build SQL by concatenating strings, and never pass a statType/column name that originated from user input.
  • Validate input at the boundary (command args, Discord message content) before it reaches the database or JDA.
  • Least-privilege configuration. Document the minimum permissions a feature needs; do not require op or administrator by default.
If you find a security issue, do not open a public issue. Report it privately to official@xreatlabs.space.

​
Reporting Issues

Non-security bugs and feature requests go through GitHub Issues. A useful report includes:
  • XDiscordUltimate version (/xdiscord shows it)
  • Server software and Minecraft version
  • Java version (java -version)
  • Database type in use (sqlite / mysql / postgresql)
  • Steps to reproduce, expected vs. actual behavior
  • Relevant log lines (with secrets redacted)

​
License

XDiscordUltimate is released under the MIT License. By submitting a pull request you agree your contributions are licensed under the same terms.

​
Next Steps

Building from Source

Set up your environment and compile the project.

GitHub Repository

Browse source, open issues, and start a pull request.