Contributing

Contributing to FCDex

Thanks for your interest in contributing to FCDex! Contributions, bug reports, suggestions, and improvements are welcome.

Before contributing

For substantial changes, open an issue first to discuss your idea. This helps avoid duplicated work and keeps contributions aligned with the project's architecture.

• View existing issues
• Create a new issue

Setting up your environment

You'll need:

• Git
• Bun
• A Discord application for testing Discord functionality
• Access to a development PostgreSQL database

Clone the repository and install its dependencies:

git clone https://github.com/saedevz/fcdex.git
cd fcdex
bun install

Generate your local configuration:

bun run setup

Configure your local credentials and database connection before running the application.

For further instructions, see Installation.

Development workflow

A typical contribution workflow looks like this:

1. Fork the repository.
2. Create a branch for your changes.
3. Implement your changes.
4. Review the affected code.
5. Run the relevant checks.
6. Commit your changes.
7. Open a pull request.

Use descriptive branch names and commit messages.

Code quality

FCDex uses TypeScript and provides scripts for linting, formatting, and building.

Run the relevant checks before submitting a contribution:

bun run lint
bun run build

To format the code, run:

bun run format

Review formatting changes before committing to avoid unrelated modifications.

Project architecture

FCDex uses a modular package architecture.

When contributing new functionality:

• Follow the conventions used by existing packages.
• Keep unrelated changes separate.
• Handle errors appropriately.
• Avoid unnecessary dependencies.
• Update configuration and documentation when needed.
• Clearly distinguish completed functionality from work in progress.

See Package System for more information.

Database changes

Database changes require particular care.

• Review the Prisma schema before modifying models.
• Consider compatibility with existing data.
• Test changes against a development database.
• Never commit real credentials.
• Back up important data before applying schema changes.
• Do not run unreviewed migrations against production databases.

BallsDex migration tooling is planned for a later development phase.

Pull requests

A useful pull request should include:

• A clear description of the change.
• The reason for the change.
• Any relevant issue references.
• The checks or tests performed.
• Screenshots or examples when useful.
• Notes about breaking changes, if applicable.

Keep pull requests focused and explain any important trade-offs.

Security

Never publish bot tokens, database passwords, private configuration files, or sensitive user data.

If you discover a potential security vulnerability, avoid posting sensitive details publicly. Contact the project maintainers through an appropriate private channel.

Community

Have questions or want to discuss a contribution?

Join the FCDex Discord community.

License

FCDex is intended to be released under the MIT License. See the repository's LICENSE file for the applicable terms.

---

Thanks for helping improve FCDex! ⚽