Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
329 lines (222 loc) · 5.75 KB

CONTRIBUTING.md

File metadata and controls

329 lines (222 loc) · 5.75 KB
Raw

Contributing

Want to help? Cool! Here's how.

Check the documentation first if you're new to the project.

Code of Conduct

Don't be a jerk. That's it.

  • Be respectful
  • Give constructive feedback
  • Help others when you can

What you need

  • Node.js 22+ and pnpm 10 (corepack enable)
  • Docker & Docker Compose v2.0+
  • Git
  • Any code editor (VS Code works great)

Setup

  1. Fork the repo

  2. Clone it:

    git clone https://github.com/YOUR_USERNAME/minepanel.git
cd minepanel

  3. Add upstream:

    git remote add upstream https://github.com/Ketbome/minepanel.git

  4. Create a branch:

    git checkout -b feature/my-thing

Ways to help

  • Fix bugs
  • Add features
  • Improve docs
  • Translate to other languages
  • Write tests
  • Make the UI better

Running locally

The repo is a pnpm workspace (backend + frontend); pnpm install at the root installs both and the git hooks. Node 22+ and pnpm 10 (corepack enable).

Backend

pnpm install
pnpm dev:backend

Runs on http://localhost:8091

Frontend

pnpm install
pnpm dev:frontend

Runs on http://localhost:3000

Documentation

pnpm install
pnpm docs:dev

Runs on http://localhost:5173

Docker

# Full stack
docker-compose -f docker-compose.split.yml up --build

# Logs
docker-compose logs -f

# Stop
docker-compose down

Project Structure

minepanel/
├── backend/              # NestJS backend API
│   ├── src/
│   │   ├── auth/        # Authentication module
│   │   ├── server-management/  # Server management logic
│   │   └── docker-compose/     # Docker operations
│   │   └── settings/           # User Settings
│   │   └── users/              # User
│   └── test/
├── frontend/            # Next.js frontend
│   ├── src/
│   │   ├── app/        # App router pages
│   │   ├── components/ # React components
│   │   ├── lib/        # Utilities and hooks
│   │   └── services/   # API services
│   └── public/
├── doc/                # VitePress documentation
│   ├── .vitepress/
│   └── *.md
└── servers/           # Minecraft server data (created at runtime)

Pull Requests

Before submitting

  1. Update from upstream:

    git fetch upstream
git rebase upstream/main

  2. Run tests:

    pnpm test

  3. Lint (pnpm verify runs lint + typecheck + tests, the same gate as the pre-push hook and CI):

    pnpm lint

  4. Test manually

Submitting

  1. Push:

    git push origin feature/my-thing

  2. Open a PR on GitHub

  3. Fill out the template:

    • What changed
    • Related issues
    • Screenshots for UI stuff
    • How to test

Title format

feat(server): add Purpur support
fix(ui): correct button alignment
docs: update installation guide

Review

  • Someone will review it
  • Make requested changes
  • It gets merged

Bug reports

Before opening an issue:

  • Check if it's already reported
  • Try the latest version
  • Get logs and screenshots

Format

## What's wrong

Clear description of the bug

## How to reproduce

1. Do this
2. Do that
3. See error

## Expected vs actual

Expected: X should happen
Actual: Y happened instead

## Environment

- OS: Ubuntu 22.04
- Docker: 24.0.0
- Minepanel: 1.0.0
- Browser: Chrome 120

## Logs

[Paste logs here]

## Screenshots

[If you have any]

Feature requests

Before suggesting:

  • Check the roadmap
  • Check existing issues
  • Make sure it fits the project

Format

## What

Brief description

## Why

What problem does it solve?

## How

Detailed explanation

## Implementation ideas

(Optional) How it could work

## Alternatives

(Optional) Other solutions considered

## Context

(Optional) Screenshots, mockups, examples

Translations

Want to add a new language?

  1. Create frontend/src/lib/translations/fr.ts:

    import type { TranslationKey } from './en';

export const fr: Record<TranslationKey, string> = {
  // Copy from en.ts and translate every key.
};

    Dictionaries must be complete: the build fails if any key from en.ts is missing.

  2. Register its dictionary and display metadata once in frontend/src/lib/translations/index.ts:

    import { fr } from "./fr";

const locales = {
  // ...
  fr: { dictionary: fr, flag: '🇫🇷', name: 'Français' },
};

    translations, Language, and languageOptions are derived from this registry. The locale code must match the dictionary import.

  3. Do not edit LanguageSwitcher, LanguageSelector, or the settings service. Both selectors render languageOptions, and the settings API uses the canonical Language type from the registry.

    Discord webhook notifications are separate backend translations and currently support only en, es, and nl. Add a backend translation only when the new locale must also be used in notifications.

  4. Test it:

    pnpm --filter ./frontend lint
pnpm --filter ./frontend build

    Also select the new locale on the login page and in Settings → Preferences.

Documentation

Docs are at minepanel.ketbome.com and built with VitePress (in doc/).

Types of docs needed:

  • API endpoints
  • User guides
  • Examples
  • Troubleshooting

Keep it:

  • Simple and clear
  • With code examples
  • Updated with changes
  • With screenshots when helpful

Questions?

Thanks for helping!