Skip to content

Collaborating on the Crystal Server Project

Jump to bottom
João Paulo edited this page Jul 20, 2025 · 3 revisions

Collaborating on the Crystal Server Project

Welcome to the Crystal Server project! To ensure a smooth and productive collaboration experience, we’ve outlined the necessary steps and tools you’ll need to contribute effectively. Follow this guide to set up your development environment and start collaborating.

1. Prerequisites

Before diving into the project, make sure you have the following software installed:

  • Git: Download and install Git from here.
  • Visual Studio Code (VS Code): Use VS Code as your code editor. Download it here.
  • StyLua Extension: Install the StyLua extension by JohnnyMorganz in VS Code for consistent Lua code formatting.
    • Open VS Code → Go to Extensions (Ctrl+Shift+X) → Search for "StyLua" → Install the extension by JohnnyMorganz.
  • Visual Studio 2022 Community: Required for building the project on Windows. Download it here. Ensure you install the compiler and the English language pack.
  • vcpkg: A package manager for C++ libraries. Clone it from here.

2. Cloning the Source Code

Run the following command to clone the Crystal Server repository:

cd C:\
git clone --recursive https://github.com/zimbadev/crystalserver.git

This will download the source code and all its dependencies.

3. Compiling the Project

For detailed instructions on compiling the project, refer to the official guides below based on your operating system:

These guides provide step-by-step instructions to set up your environment and compile the project successfully.

4. Collaborating Effectively

To ensure your contributions align with the project’s standards and goals, keep the following points in mind:

Code Formatting

  • Always use the StyLua extension to format your Lua code before committing changes. This ensures consistency across the codebase.
  • Configure StyLua with the project’s formatting rules if provided.

Commit Messages

  • Write clear and concise commit messages that describe the purpose of your changes.
  • Follow the standard format: 
    <type>: <description>

Example:
fix: resolve null pointer exception in server initialization

Branch Management

  • Create a new branch for each feature or bug fix. Avoid working directly on the main branch.
  • Name your branches descriptively, e.g., feature/add-authentication or bugfix/null-pointer.

Testing

  • Test your changes thoroughly before submitting a pull request.
  • Ensure your code passes all existing unit and integration tests.
  • Add new tests for any functionality you introduce.

Pull Requests

  • Submit a pull request (PR) for review once your changes are complete.
  • Provide a detailed description of your changes in the PR, including any relevant context or screenshots.
  • Address feedback from reviewers promptly.

5. Important Points of Attention

GitHub Actions Permissions

  • Before committing your changes, ensure that you have granted read and write permissions to the GitHub Actions workflows in the cloned repository. This is crucial for the CI/CD pipeline to function correctly and for automated builds, tests, and deployments to execute without issues.
    • To do this, go to the repository settings on GitHub → Navigate to Actions → Ensure the appropriate permissions are enabled under the Workflow permissions section.

6. Additional Tips

  • Stay Updated: Regularly pull the latest changes from the main branch to avoid merge conflicts.
  • Debugging: Use Visual Studio’s powerful debugging tools to identify and resolve issues efficiently.
  • Documentation: Update the project’s documentation if your changes affect existing functionality or introduce new features.

By following this guide, you’ll be well-equipped to contribute to the Crystal Server project. Happy coding, and thank you for your collaboration! 🚀

Clone this wiki locally