Follow these guidelines to ensure your contribution is accepted quickly and maintains the quality of the Monkeytype project.
Pull Request Naming
Monkeytype uses Conventional Commits for pull request titles and commit messages. Always include your GitHub username in parentheses at the end.
type(scope): description (@username)
- type: The kind of change (see below)
- scope: Optional. The area affected (e.g., quotes, leaderboard, auth)
- description: Brief description of the change
- username: Your GitHub username
Types
| Type | Description | Example |
|---|
feat | A new feature | feat: add dark mode toggle (@username) |
impr | An improvement to an existing feature | impr(quotes): add Spanish quotes (@username) |
fix | A bug fix | fix(leaderboard): show user rank correctly (@user1, @user2) |
docs | Documentation only changes | docs: update contribution guide (@username) |
style | Code style changes (formatting, whitespace) | style: format with Oxfmt (@username) |
refactor | Code changes that neither fix bugs nor add features | refactor: simplify test logic (@username) |
perf | Performance improvements | perf: optimize word generation (@username) |
test | Adding or updating tests | test: add unit tests for results (@username) |
build | Build system or dependency changes | build: upgrade vite to v5 (@username) |
ci | CI/CD configuration changes | ci: add deployment workflow (@username) |
revert | Revert a previous commit | revert: undo previous commit (@username) |
chore | Other changes that don’t fit above categories | chore: update dependencies (@username) |
Examples
feat: add new typing mode (@johndoe)
impr(quotes): add French quotes (@contributor)
fix(leaderboard): correct rank calculation (@dev1, @dev2)
docs: add API documentation (@writer)
refactor(backend): simplify auth logic (@architect)
For pull requests with multiple contributors, list all usernames separated by commas.
Code Standards
Monkeytype uses Oxc (Oxfmt and Oxlint) for code formatting and linting.
- Oxfmt: Automatic code formatting
- Oxlint: Fast TypeScript/JavaScript linter
These tools run automatically via pre-commit hooks. You can also run them manually:
# Check formatting
npm run format-check
# Fix formatting
npm run format-fix
# Lint code
npm run lint
# Lint with auto-fix
npm run lint-fix
Commits will be blocked if code doesn’t pass formatting and linting checks.
TypeScript Guidelines
- Use strict type checking
- Avoid
any types when possible
- Define interfaces for complex data structures
- Use descriptive variable and function names
- Add comments for complex logic
Code Style
- Follow existing code patterns in the file you’re editing
- Keep functions small and focused
- Use meaningful variable names
- Add JSDoc comments for public APIs
- Avoid deeply nested code
Theme Guidelines
Before submitting a theme, ensure:
Requirements
- Your theme is unique and visually distinct from existing themes
- Text color is black, white, or very close to these colors
- Theme is added to the themes configuration file
- The
textColor property matches the theme’s main color
- Theme is readable with both:
- “Flip test colors” enabled and disabled
- “Colorful mode” enabled and disabled
Testing Your Theme
Test your theme with different settings:
- Default mode
- Flip test colors enabled
- Colorful mode enabled
- Both flip test colors and colorful mode enabled
Ensure text remains readable in all combinations.
Theme Properties
Each theme must define these color properties:
| Property | Description |
|---|
bg | Background color |
caret | Typing cursor color |
main | Primary accent color |
sub | Secondary text color |
subAlt | Alternative background color |
text | Main text color (should be black or white) |
error | Error text color |
errorExtra | Error background color |
colorfulError | Colorful mode error text |
colorfulErrorExtra | Colorful mode error background |
Custom CSS
If your theme requires custom CSS:
- Create a CSS file in
frontend/static/themes/
- Add
hasCss: true to your theme configuration
- Keep custom styles minimal and theme-specific
Pull Request
When submitting a theme PR:
- Include screenshots showing:
- The theme in normal mode
- The theme with colorful mode
- The theme with flip test colors
- Use the PR naming format:
impr(themes): add [theme_name] (@username)
- Describe the inspiration or design concept
For detailed instructions, see Creating Themes.
Language Guidelines
Requirements
- No expletive or offensive words
- Valid JSON format (no trailing commas)
- Added to both
_list and _groups files
- File name matches word count:
language.json = 200 wordslanguage_1k.json = 1,000 wordslanguage_10k.json = 10,000 words
JSON Structure
{
"name": "Language Name",
"rightToLeft": false,
"ligatures": false,
"orderedByFrequency": true,
"bcp47": "en-US",
"words": [
"word1",
"word2",
"word3"
]
}
Field Descriptions
| Field | Type | Description |
|---|
name | string | Display name of the language |
rightToLeft | boolean | true for RTL languages (Arabic, Hebrew, etc.) |
ligatures | boolean | true if letters join together (Arabic, Malayalam, etc.) |
orderedByFrequency | boolean | true if words are sorted by frequency |
bcp47 | string | IETF language tag |
words | string[] | Array of words (minimum 200) |
Word Selection
- Use common, everyday words
- Avoid proper nouns unless commonly used
- Include words of varying lengths
- No profanity or offensive content
- Verify spelling accuracy
Pull Request
When submitting a language PR:
- Use the format:
impr(languages): add [language] (@username)
- Mention if the word list is ordered by frequency
- Note any special characteristics (RTL, ligatures, etc.)
- If applicable, credit the source of the word list
For detailed instructions, see Adding Languages.
Quote Guidelines
Requirements
- No unlawful, abusive, or obscene content
- Valid JSON format (no trailing commas)
- Not a duplicate of existing quotes
- Correct
length property (character count)
- Correctly incremented
id property
- Minimum 60 characters in length
JSON Structure
{
"text": "The quote text goes here.",
"source": "Author Name or Source",
"id": 1234,
"length": 25
}
Field Descriptions
| Field | Type | Description |
|---|
text | string | The quote text (min 60 characters) |
source | string | Author or source of the quote |
id | number | Unique ID (increment from last quote) |
length | number | Character count of the text |
Quote Selection
- Choose meaningful or interesting quotes
- Verify attribution accuracy
- Avoid controversial or sensitive content
- Check for duplicates in the existing file
- Ensure proper grammar and punctuation
Non-English Quotes
For quotes not in English:
- Include translations in your PR description
- This helps maintainers verify the content
- Explain any cultural context if relevant
Pull Request
When submitting a quote PR:
- Use the format:
impr(quotes): add [language] quotes (@username)
- For non-English quotes, include translations in the description
- Mention the number of quotes added
- Verify all IDs are sequential
For detailed instructions, see Adding Quotes.
Layout Guidelines
If you want to contribute keyboard layouts:
- Check the existing layouts in
frontend/static/layouts/
- Follow the same JSON structure as existing layouts
- Ensure accurate key mappings
- Test thoroughly with the typing test
For more details, refer to the LAYOUTS.md file in the repository.
General Best Practices
Before Submitting
Writing Good Descriptions
- Explain what changed and why
- Provide context for the change
- Link to related issues
- Add screenshots or GIFs for UI changes
- List any breaking changes
- Mention testing performed
Responding to Feedback
- Be receptive to suggestions
- Ask questions if feedback is unclear
- Make requested changes promptly
- Thank reviewers for their time
- Update your PR when ready for re-review
Multiple Contributors
If multiple people worked on the PR:
- List all contributors in the PR title:
(@user1, @user2, @user3)
- Credit specific contributions in the description
- Ensure all contributors are acknowledged
Asset Validation
Before submitting changes to languages, quotes, or themes, run validation:
# Validate all assets
npm run check-assets
# Validate specific types
npm run check-assets-quotes
npm run check-assets-languages
npm run check-assets-others
Commit Messages
While pull request titles follow Conventional Commits, individual commit messages should:
- Be descriptive and clear
- Start with a lowercase verb (“add”, “fix”, “update”, etc.)
- Keep the first line under 72 characters
- Add more details in the body if needed
Good Commit Messages
fix: correct leaderboard rank display
add: Spanish quote collection
update: theme color contrast for accessibility
refactor: simplify authentication flow
Avoid
fixed stuff
update
changes
wip
Documentation
If your change affects user-facing features:
- Update relevant documentation
- Add code comments for complex logic
- Update API documentation if applicable
- Consider adding examples
Questions and Support
If you have questions about these guidelines:
Enforcement
These guidelines help maintain code quality and consistency. Pull requests that don’t follow these guidelines may be:
- Requested to make changes
- Delayed in review
- Closed if changes aren’t made
Following these guidelines ensures a smooth contribution process and faster acceptance of your work.