110 lines
4.2 KiB
Markdown
110 lines
4.2 KiB
Markdown
# Contributing to Pumpkin Documentation
|
|
|
|
We appreciate your interest in contributing to the Pumpkin documentation! High-quality documentation helps developers, server administrators, and plugin creators understand and adopt Pumpkin.
|
|
|
|
> [!NOTE]
|
|
> - **Looking to contribute to the Pumpkin server codebase?** Please consult the **[Pumpkin Core Developer & Contributing Guide](https://pumpkinmc.org/developer/contributing)** or the [`CONTRIBUTING.md`](https://github.com/Pumpkin-MC/Pumpkin/blob/master/CONTRIBUTING.md) in the main Pumpkin repository.
|
|
> - **Looking to contribute to documentation or translations?** You are in the right place! Read on below.
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
Join our community and ask questions in [our Discord server](https://discord.gg/wT8XjrjKkf) in the `#development` channel.
|
|
|
|
### Ways to Contribute
|
|
|
|
- **Fixing Typos & Improving Phrasing**: Clarify instructions, fix grammar, or fix dead links across any documentation page.
|
|
- **Documenting New Features**: Add or update documentation as new features land in Pumpkin.
|
|
- **Adding Examples**: Add code snippets, configuration examples, and tutorials.
|
|
- **Adding or Updating Translations**: Help localize Pumpkin documentation for users worldwide.
|
|
|
|
---
|
|
|
|
## Local Development Setup
|
|
|
|
This documentation site is built with [VitePress](https://vitepress.dev/) and powered by Node.js / Bun.
|
|
|
|
### 1. Prerequisites
|
|
|
|
- [Node.js](https://nodejs.org/) (v18+) or [Bun](https://bun.sh/)
|
|
- [Git](https://git-scm.com/)
|
|
|
|
### 2. Setup & Running
|
|
|
|
```bash
|
|
# Clone the documentation repository
|
|
git clone https://github.com/Pumpkin-MC/Pumpkin-Docs.git
|
|
cd Pumpkin-Docs
|
|
|
|
# Install dependencies
|
|
bun install
|
|
# or: npm install
|
|
|
|
# Start local development server with hot-reload
|
|
bun run dev
|
|
# or: npm run dev
|
|
```
|
|
|
|
Visit the displayed localhost address (typically `http://localhost:5173`) in your browser.
|
|
|
|
### 3. Verification
|
|
|
|
Before submitting a pull request, verify that the documentation builds cleanly and has no typos:
|
|
|
|
```bash
|
|
# Verify static build passes
|
|
bun run build
|
|
# or: npx vitepress build docs
|
|
|
|
# Check for spelling errors
|
|
typos
|
|
```
|
|
|
|
---
|
|
|
|
## Adding a Translation
|
|
|
|
To add a new language translation:
|
|
|
|
1. Create a new locale configuration file in `docs/.vitepress/` (e.g., `fr.ts` for French).
|
|
2. Register the new locale in `docs/.vitepress/config.ts`.
|
|
3. Duplicate the English documentation folder (`docs/en/`) and rename it to your language's ISO code (e.g., `docs/fr/`).
|
|
4. Translate all markdown files in the newly created folder, updating links to preserve the locale prefix.
|
|
5. Add the translation folder to the exclude list in `.typos.toml` if your language uses non-English words.
|
|
6. Run `bun run build` to verify that there are no broken links or syntax errors.
|
|
|
|
---
|
|
|
|
## Pull Request & Commit Guidelines
|
|
|
|
All contributions submitted via Pull Requests to the Pumpkin documentation repository must follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
|
|
|
|
### Format
|
|
|
|
```text
|
|
<type>(<optional scope>): <imperative summary>
|
|
```
|
|
|
|
### Allowed Types
|
|
|
|
| Type | Purpose | Example |
|
|
| :--- | :--- | :--- |
|
|
| `docs` | Documentation additions, revisions, or expansions | `docs(entities): document mob goal selector` |
|
|
| `fix` | Correcting typos, dead links, or factual errors | `fix(proxy): fix velocity forwarding port reference` |
|
|
| `feat` | Adding a completely new guide, section, or interactive component | `feat(commands): add Brigadier execution context guide` |
|
|
| `refactor` | Restructuring files or configs without content changes | `refactor(locales): add explicit ts extensions to imports` |
|
|
| `chore` | Tooling, dependency, or build configuration updates | `chore(deps): update vitepress` |
|
|
|
|
### Key Rules
|
|
|
|
- **Use Imperative Mood**: Write `add`, not `added` or `adds`; `fix`, not `fixed` or `fixes`.
|
|
- **Lowercase**: Start descriptions with a lowercase letter and omit trailing punctuation.
|
|
- **PR Title**: Ensure your GitHub Pull Request title follows the Conventional Commits format, as it is used for automated squash commits and release changelogs.
|
|
|
|
---
|
|
|
|
## Code of Conduct
|
|
|
|
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
|