Contributing Guide

​

Ways to Contribute

• Try Plane Cloud and self-hosting and provide feedback
• Add new integrations
• Add or update translations
• Help with open issues or create your own
• Share your thoughts and suggestions
• Help create tutorials and blog posts
• Request features by submitting proposals
• Report bugs
• Improve documentation - fix incomplete or missing docs, bad wording, examples, or explanations

​

Before You Start

​

Search Existing Issues

​

Set Up Your Development Environment

​

Submitting Issues

​

Creating Quality Bug Reports

• Third-party libraries being used and their versions
• A specific use case that fails
• Steps to reproduce the issue
• Expected vs. actual behavior

​

Naming Conventions for Issues

• Bugs: 🐛 Bug: [short description]
• Features: 🚀 Feature: [short description]
• Improvements: 🛠️ Improvement: [short description]
• Documentation: 📘 Docs: [short description]

• 🐛 Bug: API token expiry time not saving correctly
• 📘 Docs: Clarify RAM requirement for local setup
• 🚀 Feature: Allow custom time selection for token expiration

​

Feature Requests

1. Submit a feature request
2. If you want to implement it yourself, submit an issue with your proposal first to ensure alignment with project goals
3. Follow the coding guidelines below

​

Coding Guidelines

​

Code Style

• TypeScript: Strict mode enabled, all files must be typed
• Naming Conventions:
  • camelCase for variables and functions
  • PascalCase for components and types
• Imports:
  • Use workspace:* for internal packages
  • Use catalog: for external dependencies

​

Linting and Formatting

pnpm check:format

• .oxlintrc.json - Linting rules
• .oxfmtrc.json - Formatting rules

​

Testing

• All features or bug fixes must be tested by one or more specs (unit tests)
• Use the existing test framework for each package
• Run tests before submitting your pull request

​

Error Handling

• Use try-catch blocks with proper error types
• Log errors appropriately using the logger package
• Provide meaningful error messages

​

State Management

• MobX stores should be placed in packages/shared-state
• Follow reactive patterns
• Use observables, computed values, and actions appropriately

​

Component Development

• Build reusable components in @plane/ui
• Use Storybook for isolated development and testing
• Start Storybook: pnpm --filter=@plane/ui storybook

​

Contributing Translations

​

Translation Structure

packages/i18n/src/locales/
    ├── en/
    │   ├── core.json       # Critical translations
    │   └── translations.json
    ├── fr/
    │   └── translations.json
    └── [language]/
        └── translations.json

​

Translation Format

{
  "greeting": "Hello, {name}!"
}

{
  "items": "{count, plural, one {Work item} other {Work items}}"
}

​

Updating Translations

1. Locate the key in locales/<language>/translations.json
2. Update the value while keeping the key structure intact
3. Preserve any existing ICU formats (variables, pluralization)

​

Adding New Translation Keys

1. Add the key to all language files
2. Use English as a placeholder if translations aren’t immediately available
3. Keep the nesting structure consistent across all languages
4. Apply ICU format uniformly if using dynamic content

​

Adding New Languages

export type TLanguage = "en" | "fr" | "your-lang";

export const SUPPORTED_LANGUAGES: ILanguageOption[] = [
  { label: "English", value: "en" },
  { label: "Your Language", value: "your-lang" },
];

private importLanguageFile(language: TLanguage): Promise<any> {
  switch (language) {
    case "your-lang":
      return import("../locales/your-lang/translations.json");
    // ...
  }
}

​

Translation Quality Checklist

• All translation keys exist in every language file
• Nested structures match across all languages
• ICU message formats are correctly implemented
• All languages load without errors
• Dynamic values and pluralization work as expected
• No missing or untranslated keys

​

Pull Request Process

1. Fork the repository and create your branch from master
2. Make your changes following the coding guidelines
3. Test your changes thoroughly
4. Run checks: pnpm check to ensure code quality
5. Commit your changes with a clear commit message
6. Push to your fork and submit a pull request
7. Wait for review - maintainers will review your PR and provide feedback

​

Pull Request Guidelines

• Provide a clear description of the changes
• Reference any related issues
• Include screenshots for UI changes
• Ensure all checks pass
• Be responsive to feedback

​

Getting Help

• Forum: forum.plane.so
• GitHub Discussions: GitHub
• Documentation: docs.plane.so

​

Next Steps

• Set up your development environment
• Learn about Plane’s architecture
• Explore open issues to find something to work on