Skip to content

feat: streamline contributing guide #1571

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
maxprilutskiy merged 4 commits into from
Nov 12, 2025
Merged

feat: streamline contributing guide #1571

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5f2fe7d
feat: streamline contributing guide
maxprilutskiy Nov 12, 2025
3aa7084
feat: add assignment priority and anti-spam rules
maxprilutskiy Nov 12, 2025
daef122
chore: resolve merge conflict, keep streamlined version
maxprilutskiy Nov 12, 2025
b64433f
docs: add prompt response requirement for maintainer comments
maxprilutskiy Nov 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 49 additions & 180 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,209 +1,78 @@
# CONTRIBUTING.md
# Contributing to Lingo.dev

Thank you for contributing to Lingo.dev! We're an exciting open source project and we love having you contribute!
Thank you for contributing! We maintain high standards for code quality and design.

Here are some resources and guidance to help you get started:
**IMPORTANT: Every requirement below is critical. If any requirement is not met, your issue or PR will be automatically rejected by the bots.**

1. [Getting Started](#getting-started)
2. [Issues](#issues)
3. [Pull Requests](#pull-requests)
4. [Release Process](#release-process)
## Before You Start

## Getting Started
1. **Find or create an issue** - Search [existing issues](https://github.com/lingodotdev/lingo.dev/issues) first
2. **Wait to be assigned** - Comment on the issue and wait for assignment before starting work. Assignment priority:
- First: Issue creator
- Second: First volunteer commenter
- **Submitting a PR without assignment will result in automatic rejection**
3. **Discuss approach** - Align on implementation details before coding

Here's how to get the project running locally:
## Pull Request Requirements

### Must Have

- **Linked issue** - Reference the issue in your PR (e.g., "Closes #123")
- **Valid title** - Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `chore:`, etc.
- **Tests** - Unit tests for main code paths
- **Changeset** - Run `pnpm new` from repo root
- **Passing checks** - All CI checks must pass

### Standards

- **Surgical PRs** - One clear objective per PR
- **Clean code** - Elegant, well-reasoned implementation
- **Meaningful changes** - No low-effort, cosmetic, or trivial edits made only to gain contributions
- **No duplicate work** - Check if someone else already opened a PR

## Local Development

### Prerequisites

- **Node.js**: Make sure you have Node.js version 18 or higher installed.
- **pnpm**: You can install using this command `npm install -g pnpm` or by following [this guide](https://pnpm.io/installation)
- **AI API Key**:
Currently, Groq, Google, and Mistral are supported.
- **GROQ API Key**: You can get one by signing up at [Groq](https://console.groq.com/)
- **GOOGLE API Key**: You can get one in the [Google AI Studio](https://aistudio.google.com/apikey)
- **MISTRAL API Key**: You can get one by signing up at [Mistral AI](https://console.mistral.ai)
- Node.js 18+
- pnpm (`npm install -g pnpm`)
- AI API key (Groq, Google, or Mistral) - [setup guide](https://lingo.dev/en/cli/quick-start#step-2-authentication)

### Setup

To set up the project, clone the repository and install the dependencies:

```bash
git clone https://github.com/lingodotdev/lingo.dev
cd lingo.dev
pnpm install
pnpm turbo build
```

Next, configure an AI API key. You can use either a Lingo.dev API key or one of the supported LLM model providers.

Please refer to our docs on how to set this up: https://lingo.dev/en/cli/quick-start#step-2-authentication

_Note:_ When loading LLM API keys (both Lingo.dev and other LLM model providers like Groq or Mistral), the Lingo.dev Compiler checks the following sources in order of priority:

1. Environment variables (via `process.env`)
2. Environment files (`.env`, `.env.local`, `.env.development`)
3. Lingo.dev configuration

Next, you can run the project using the following commands:
### Run Locally

```bash
# start the build process
pnpm turbo build

# in terminal window 1 - watch for CLI code changes
# Terminal 1 - watch CLI changes
cd packages/cli
pnpm run dev

# in terminal window 2 - test the CLI
# Terminal 2 - test CLI
cd packages/cli
pnpm lingo.dev --help # this command will use the current CLI code + demo config from ./packages/cli/i18n.json
pnpm lingo.dev --help
```

Feel free to ask questions on our [Discord server](https://lingo.dev/go/discord)!

## Adding a New LLM Provider

Want to add support for a new LLM provider to Lingo.dev? Here's a checklist to help you get started:

1. **Add Your Dependency**

- Install the relevant SDK/package for your provider in the necessary `package.json` (usually `cli` and/or `compiler`). Lingo.dev uses the [AI SDK](https://ai-sdk.dev) and its [providers](https://ai-sdk.dev/providers/ai-sdk-providers), so check first to make sure the AI SDK supports your provider.

2. **Update the Config Schema**

- Edit [`packages/spec/src/config.ts`](./packages/spec/src/config.ts) and update the list of allowed provider `id` values to include your new provider.

3. **Provider Details**

- Add your provider to [`packages/compiler/src/lib/lcp/api/provider-details.ts`](./packages/compiler/src/lib/lcp/api/provider-details.ts) with name, env var, config key, API docs, and signup link.

4. **API Key Handling**

- Update [`packages/compiler/src/utils/llm-api-key.ts`](./packages/compiler/src/utils/llm-api-key.ts) to add functions for getting the API key from environment/config.

5. **CLI and Compiler Logic**

- Update the CLI (e.g., [`packages/cli/src/cli/localizer/explicit.ts`](./packages/cli/src/cli/localizer/explicit.ts), [`packages/cli/src/cli/processor/index.ts`](./packages/cli/src/cli/processor/index.ts)) to support your provider.
- Update the compiler's translation logic to instantiate your provider's client (see [`packages/compiler/src/lib/lcp/api/index.ts`](./packages/compiler/src/lib/lcp/api/index.ts)).

6. **Error Handling**

- Ensure user-facing error messages are updated to mention your provider where relevant (API key checks, troubleshooting, etc).

7. **Test and Document**
- Add or update tests to cover your provider.
- Update documentation and this contributing guide as needed.
### Run Checks

**Tip:**
Look at how existing providers like "groq", "google", and "mistral" are implemented for reference. Consistency helps us maintain quality and predictability!

## Issues

If you find a bug, please create an Issue and we'll triage it.

- Please search [existing Issues](https://github.com/lingodotdev/lingo.dev/issues) before creating a new one
- Please include a clear description of the problem along with steps to reproduce it. Exact steps with screenshots and URLs really help here
- Before starting work on an issue, please comment on it and wait for it to be assigned to you. This prevents multiple people from working on the same issue simultaneously
- Let's discuss implementation details in the issue comments or Discord before starting work, to ensure alignment between contributors and the Lingo.dev team

---

## 🧩 Issue Assignment Rules
To maintain fairness and quality in our open-source contributions, we follow these rules for issue assignment:

### 🧠 Issue Assignment Priority
1. **First priority:** The person who opened the issue.
2. **Second priority:** The first commenter who volunteers to work on it (if the issue creator is not working on it).

> ❌ Submitting a PR without being assigned may result in rejection — even if it solves the issue.

---

### 🚀 Pull Request Etiquette

- Avoid submitting **low-effort or spammy PRs** (e.g., cosmetic or trivial edits made only to gain contributions).
- Use **Conventional Commit** titles: `feat:`, `fix:`, `docs:`, `chore:`, etc.
- Provide a **clear and meaningful PR description** linking to the related issue.
- Make sure your PR passes all CI checks and formatting standards.

> ✅ Ideal PRs are thoughtful, well-tested, and make meaningful improvements to the codebase.


## Pull Requests

We love your Pull Requests! However, we maintain extremely high standards for code quality and design. We are looking for elegant, 12/10, beautiful code and deeply weighted system design decisions.

### Our Standards

- **Surgical PRs**: Pull requests must be surgical and extremely single-purposed. One clear objective per PR.
- **Elegant Code**: We expect beautifully crafted, elegant code that demonstrates mastery of the language and patterns.
- **Deep Design Thinking**: System design decisions must be deeply considered and well-reasoned.
- **Comprehensive Testing**: Must include tests that surgically test both positive and negative paths of the code.
- **Uncompromising Quality**: We prefer fewer, higher-quality contributions over numerous mediocre ones.

A couple of things to keep in mind before you submit:

### Before you open a pull request

- GitHub Issue
- Make sure the fix or feature is sufficiently documented and discussed in advance in an existing [GitHub Issue](https://github.com/lingodotdev/lingo.dev/issues)
- If there are no related issues, **we strongly suggest you [create a new Issue](https://github.com/lingodotdev/lingo.dev/issues/new)** and discuss your feature or proposal with the Lingo.dev team
- If there is a Discord thread already, please summarize it in a GitHub Issue. This helps to keep everyone in the loop, including open-source contributors and Lingo.dev team members not part of the original conversation. It also serves as documentation for future decisions.
- README update
- If applicable, please add a section with the CLI commands introduced in your PR (what their purpose is and how to use them)
- It is not necessary to update the README file for every change, oftentimes a comprehensive description in the Issue or PR description is enough
- Tests
- Your changes should include unit tests for the main code paths, to make sure nothing breaks
- Changeset
- Add a [changeset](https://github.com/changesets/changesets) for your feature or fix (run `pnpm new` from the repo root)
- PR checks
- Make sure all checks pass
- You can run the checks locally in repo root:
```sh
pnpm install --frozen-lockfile
pnpm format:check
pnpm turbo build --force
pnpm turbo test --force
pnpm changeset status --since origin/main
```
...or let GitHub run it in the PR for you.

### Opening a pull request

- GitHub Issue
- Make sure to link your PR to the existing Issue(s)
- We may not be able to accept new features without existing Issues
- This does not apply to smaller fixes with sufficient description in the PR
- Existing PRs
- Make sure someone else hasn't already created a PR fixing the same issue.
- PR title
- The title should be [a valid Conventional Commit title](https://github.com/amannn/action-semantic-pull-request?tab=readme-ov-file#action-semantic-pull-request)
- Should start with `feat:`, `fix:`, `chore:`, etc.
- PR description
- Should contain sufficient description of your PR (unless the linked Issue already does)
- _💡 Tip:_ Oftentimes less is more. Try to write in your own words; real humans are reviewing your PR.
- Demo video
- For larger features we would really appreciate a quick screen recording showing it in action
- It helps make the review process faster
- You can use [open-source Cap](https://github.com/CapSoftware/Cap), [QuickTime on Mac](https://support.apple.com/guide/quicktime-player/record-your-screen-qtp97b08e666/mac), or any other software you prefer

### Review Process

- We will always try to accept the first viable PR that resolves the Issue
- Please discuss implementation approach beforehand to avoid having PRs rejected
- Please actively discuss with the Lingo.dev team in the PR and related Issue(s)

#### Automated Code Review

We use Claude Code to provide automated code reviews on all pull requests. This helps ensure:

- Code quality and maintainability
- Security best practices
- Performance considerations
- Proper test coverage
- Documentation completeness
```bash
pnpm install --frozen-lockfile
pnpm format:check
pnpm turbo build --force
pnpm turbo test --force
pnpm changeset status --since origin/main
```

The automated review will post comments on your PR with suggestions and feedback. While these are helpful guidelines, human reviewers will make the final decisions. If Claude Code identifies critical security issues, please address them promptly.
## Review Process

---
- Automated code review by AI bots provides suggestions
- Human reviewers make final decisions
- **Address maintainer comments promptly** - PRs with unaddressed comments will be closed to keep the repo clean. Feel free to recreate once issues are resolved.

Thank you!
Questions? Join our [Discord](https://lingo.dev/go/discord)!
Loading