Skip to main content
Thank you for considering contributing to OpenFront! This guide will help you understand our contribution process and requirements.

Play the Game

Experience OpenFront live

Development Discord

Join the developer community

GitHub Issues

Find issues to work on

Translation Project

Help translate the game

​
Getting Started

​
Prerequisites

Before contributing, ensure you have:
  • Node.js (recent version)
  • npm 10.9.2 or higher
  • Git for version control
  • Familiarity with TypeScript
If you haven’t set up your development environment yet, see the Development Setup guide.

​
Initial Setup

1

Fork the Repository

Fork OpenFrontIO on GitHub
2

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/OpenFrontIO.git
cd OpenFrontIO
3

Install Dependencies

npm run inst
Always use npm run inst instead of npm install to ensure security and consistency.
4

Verify Setup

npm run dev
The game should open in your browser at http://localhost:9000.

​
Contribution Path

OpenFront uses a progressive contribution system based on experience level:

​
1. New Contributors

Allowed:
  • UI improvements and styling
  • Small bug fixes
  • Documentation updates
  • Translation contributions
Why this limitation?
  • Helps you become familiar with the codebase
  • UI changes are easier to review
  • Lower risk of breaking core functionality
  • Higher acceptance rate for focused PRs

​
2. Established Contributors

After several successful PRs demonstrating codebase understanding:
  • Feature implementations
  • Larger refactoring efforts
  • Client-side enhancements
  • Non-critical server changes

​
3. Core Contributors

Only contributors with extensive project experience may modify:
  • Core game simulation (/src/core)
  • Critical game systems
  • Server coordination logic
  • Security-sensitive code
This system ensures code quality and project stability while providing a clear path for new contributors to grow.

​
Development Workflow

​
1. Before Starting Work

1

Find or Create an Issue

  • Search existing issues
  • Comment on the issue to claim it
  • For new features, create an issue first
2

Wait for Maintainer Feedback

  • Small improvements can proceed directly
  • Larger changes require maintainer approval
  • This prevents wasted effort on rejected features
3

Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-number-bug-name

​
2. Coding Standards

npm run format
The project uses Husky with lint-staged to automatically format and lint code on commit.

​
Code Quality Requirements

  • Follow existing style patterns
  • Add comments for complex logic
  • Use meaningful variable names
  • Keep functions focused and small
  • Avoid unnecessary dependencies

​
3. Testing

All new features and bug fixes must include tests: 
npm test
All code changes in /src/core MUST be tested to ensure game logic stability.
See the Testing Guide for details on writing tests.

​
4. Commit Your Changes

Write clear, concise commit messages: 
git commit -m "Add territory selection highlight"
git commit -m "Fix alliance donation calculation"
git commit -m "Update rendering performance for large maps"
Commit Message Guidelines:
  • Use present tense (“Add feature” not “Added feature”)
  • Start with a verb (Add, Fix, Update, Remove)
  • Be specific about what changed
  • Keep first line under 72 characters

​
5. Push to Your Fork

git push origin feature/your-feature-name

​
Submitting a Pull Request

​
Opening the PR

1

Go to Original Repository

Navigate to openfrontio/OpenFrontIO
2

Click 'New Pull Request'

Select your fork and branch
3

Fill Out PR Template

Complete all sections of the PR template

​
PR Checklist

Before submitting, ensure:
  • Linked the relevant issue (e.g., Resolves #123)
  • Added screenshots for UI changes
  • Processed text through translateText() and added strings to en.json
  • Added/updated tests in the tests/ directory
  • Verified npm test passes
  • Ran npm run format and npm run lint
  • Provided Discord username for communication
  • Tested changes in development environment
  • Described testing process in PR description

​
PR Description Template

## Description
Brief description of what this PR does

## Related Issue
Resolves #123

## Changes Made
- Change 1
- Change 2
- Change 3

## Screenshots (if applicable)
[Add screenshots here]

## Testing
- [ ] Tested locally
- [ ] Tested on multiple browsers
- [ ] Added unit tests
- [ ] All tests pass

## Discord Username
@username#1234

​
Review Process

  1. Maintainer Review: The project maintainer (evan) reviews all PRs
  2. Feedback: You may receive requests for changes
  3. Be Responsive: Respond to feedback promptly
  4. Approval: Maintainer approval is required before merge
  5. Merge: Maintainer will merge approved PRs
The maintainer has final authority on all code changes and design decisions. Not all contributions will be accepted.

​
Special Areas

​
Core Game Logic (/src/core)

Changes to /src/core require:
  • Extensive testing
  • Proof of determinism
  • Core contributor status
  • Maintainer pre-approval
The core must remain deterministic because each client runs its own simulation. Any non-determinism will cause game state to diverge between players.

​
Translations

OpenFront uses Crowdin for translations:
1

Join Translation Discord

discord.gg/3zZzacjWFr
2

Access Crowdin Project

crowdin.com/project/openfront-mls
3

Select Your Language

Choose your language or request a new one
4

Translate Strings

Follow Crowdin’s interface to translate
When adding new UI text in code, always use translateText() and add the English string to en.json.

​
Documentation

Documentation improvements are always welcome:
  • Fix typos or unclear sections
  • Add missing information
  • Improve code examples
  • Update outdated content

​
Project Governance

OpenFront is maintained by evan who has final authority on:
  • Code changes and design decisions
  • Pull request acceptance/rejection
  • Project direction and features
  • Contributor status advancement
Why this structure?
  • Maintains consistent vision
  • Ensures code quality
  • Enables quick decisions
  • Protects long-term stability

​
Communication

Development Discord

Technical discussions and questions

GitHub Issues

Bug reports and feature requests

​
Communication Guidelines

  • Be respectful and constructive
  • Search existing issues before posting
  • Provide context and details
  • Stay on topic
  • Accept feedback gracefully

​
Tips for Success

Begin with small UI improvements or bug fixes to learn the codebase. Don’t jump into complex features immediately.
Don’t hesitate to ask for clarification on Discord. It’s better to ask than to waste time on the wrong approach.
Study how similar features are implemented. Follow existing patterns and conventions.
Test your changes in multiple scenarios. Consider edge cases and error conditions.
One PR should address one issue. Don’t bundle multiple unrelated changes.
Reviews take time. Maintainers balance multiple responsibilities.

​
Common Mistakes to Avoid

  • Using npm install instead of npm run inst
  • Modifying core game logic as a new contributor
  • Submitting PRs without tests
  • Ignoring lint/format errors
  • Not linking related issues
  • Bundling multiple features in one PR
  • Making breaking changes without discussion

​
License

By contributing, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0 (AGPL v3.0). See LICENSE for full details.

​
Thank You!

Your contributions help make OpenFront better for everyone. Whether you’re fixing a typo, translating text, or implementing a feature, your effort is appreciated. Remember: quality over quantity. A well-tested, focused PR is more valuable than a large, unfocused one.

Architecture

Understand the system design

Setup Guide

Set up your environment

Testing Guide

Write effective tests

Build docs developers (and LLMs) love

Get started for freeTalk to us