Getting Started with Contributions

Welcome! Pano is an open-source project and we love community contributions. Whether you're fixing bugs, adding new features, or improving documentation, your help is appreciated.

📦 Our Repositories

Pano is composed of several repositories, each serving a specific purpose:

• Pano (Core): The main backend repository (Kotlin/Vert.x).
• panel-ui: The administrative management interface (SvelteKit).
• setup-ui: The initial setup wizard (SvelteKit).
• vanilla-theme: The default official theme (SvelteKit).
• pano-mc-plugin: Minecraft server-side integration plugin.
• docs: This documentation repository.

🚀 Release Types

We maintain three stages of releases across our branches:

Type	Branch	Stability	Description
Alpha	alpha	Low	Active development, frequent updates. May contain breaking changes.
Beta	beta	Medium	Pre-release stage. Generally stable but may have minor bugs.
Release	main	High	Production-ready. The most stable version.

🛠️ Technology Stack

Pano is built using modern technologies to ensure performance and flexibility:

• Backend: Kotlin, Vert.x, Spring DI, targeting JVM 11+.
• Frontend: SvelteKit, Bootstrap 5, SASS.
• Runtime: Bun is used for running our frontend services.
• Packaging: Projects are packaged into ZIP files and embedded into a single executable JAR file.

📜 Contribution Guidelines

To maintain a high-quality codebase, please follow these guidelines:

• Branching Policy:
  • Pano (Core): The active development branch is alpha. All Pull Requests should be opened against the alpha branch.
  • UI Projects: These projects typically have two branches, but dev is the default branch for active development. Please target the dev branch for your PRs.
• Conventional Commits: We follow the Conventional Commits specification. This is strictly required for all commit messages.
• Semantic Versioning & Release: Pano uses Semantic Versioning (SemVer) and Semantic Release. Commit messages are used to automatically generate changelogs and determine version numbers.
• Auto Deployment: We use GitHub Actions for continuous integration and automatic deployment.
• Database Support: We aim to support MariaDB and MySQL 5.5+. Ensure your database queries and schema changes are compatible with these versions.
• Migrations: We pay close attention to configuration and database migrations, striving to maintain backward compatibility whenever possible.
• Code Formatting: Please ensure your code follows the general structure and style of the existing project.
• AI-Generated Code: Using AI to generate code is allowed; however, we cannot accept any code that is private, proprietary, or subject to licenses that conflict with our open-source goals.
• Quality: PRs should be clean, well-commented where necessary, and tested before submission.

🧩 How Pano Works

Pano is not a traditional web script. It's a self-contained platform that runs as a single JAR file (similar to a Minecraft server). When you run the JAR:

1. It extracts the necessary UI files.
2. It downloads a portable Bun runtime.
3. Startup Checks:
   • It checks if the platform is already installed.
   • It performs configuration migrations to ensure compatibility with the current version.
   • If the platform is installed, it checks and applies database migrations.
4. It starts a backend service that acts as a reverse proxy, directing traffic to the appropriate interfaces:
   • If the platform is not installed, it directs all traffic to setup-ui.
   • If the platform is installed, it directs traffic to vanilla-theme by default.
   • Any routes starting with /panel are proxied to panel-ui.
5. It communicates with Minecraft servers via an encrypted WebSocket connection.

---

Ready to dive in? Check out the specific development guides for Backend and Frontend.