> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/ru/contributing/how-to-contribute.md).

# Как внести вклад

Дисциплина веток, рекомендации по pull request и стиль сообщений коммитов.

MyIP — проект с открытым исходным кодом и рад внешним вкладам. Эта страница описывает рабочий процесс, который проект действительно использует, от первого issue до слитого pull request.

Всё здесь повторяет [`CONTRIBUTING.md`](https://github.com/jason5ng32/MyIP/blob/main/CONTRIBUTING.md) и `AGENTS.md` в репозитории. У проекта также есть [Кодекс поведения](https://github.com/jason5ng32/MyIP/blob/main/CODE_OF_CONDUCT.md) (Contributor Covenant). Участвуя, вы соглашаетесь соблюдать его.

## Прежде чем писать код

Сначала откройте issue для всего, что не является тривиальным. Короткое обсуждение заранее дешевле, чем отклонённый pull request. Новые функции, изменения поведения, новые зависимости и рефакторинги — всё это подходит.

Небольшие, очевидные исправления — опечатка, битая ссылка, однострочный баг — можно сразу отправлять в pull request.

Если вы новичок в проекте, ищите issues с меткой `хорошая первая задача`.

## Порядок действий

{% stepper %}
{% step %}

### Откройте issue

Опишите изменение и почему оно нужно. Подождите, пока сопровождающий подтвердит направление, прежде чем вкладывать время. См. [Сообщение об issue](/developer/ru/contributing/reporting-issues.md).
{% endstep %}

{% step %}

### Сделайте форк и создайте ветку от `dev`

Сделайте форк репозитория, затем создайте свою ветку от **`dev`** — не `main`.

```bash
git clone https://github.com/<you>/MyIP.git
cd MyIP
git checkout dev
git checkout -b fix/mac-input-validation
```

{% endstep %}

{% step %}

### Настройка и сборка

Установите через pnpm и запустите приложение. См. [Среда разработки](/developer/ru/development/dev-environment.md).

```bash
pnpm install
pnpm dev
```

{% endstep %}

{% step %}

### Внесите изменение

Одна задача на ветку. Следуйте [Соглашениям по коду](/developer/ru/development/coding-conventions.md), и добавьте или обновите тесты в `tests/` для любой нетривиальной логики, которую вы затрагиваете.
{% endstep %}

{% step %}

### Запустите `pnpm check`

`pnpm check` запускает набор тестов и production-сборку. Перед push всё должно быть зелёным.

```bash
pnpm check
```

{% endstep %}

{% step %}

### Сделайте rebase на последнюю `dev`

Rebase — не merge `dev` в свою ветку. Это делает историю читаемой.

```bash
git fetch upstream
git rebase upstream/dev
```

{% endstep %}

{% step %}

### Откройте pull request против `dev`

Заполните шаблон pull request: краткое описание, тип изменения и чек-лист. Укажите issue, которое оно исправляет.
{% endstep %}
{% endstepper %}

## Почему pull request нацелен на `dev`

{% hint style="warning" %}
**Никогда не открывайте pull request в `main`.** `main` получает только release-слияния из `dev` ветки. Pull request, нацеленный на `main` попросят перенаправить.
{% endhint %}

Репозиторий `dev` — в, `dev` — наружу. Вся работа попадает в `dev` сначала; `main` попадает только через `dev` → `main` release-слияние. Это сохраняет `main` согласованность с тем, что релизится, и означает, что каждое изменение проверяется на `dev` сначала.

## Правила pull request

* **Цель `dev`.** См. выше.
* **Одна задача на pull request.** Не объединяйте функцию с не связанным с ней изменением dev-среды. Разделите их.
* **Сделайте rebase перед отправкой**, чтобы ваша ветка находилась поверх текущей `dev`.
* **Опишите, что изменилось и почему.** Рецензентам не должно быть нужно восстанавливать намерение по diff.
* **`pnpm check` зелёным.** CI запускает `pnpm test` и `pnpm run build` на Node 24 для каждого pull request к `dev` или `main`; красный запуск блокирует слияние.

## Стиль сообщений коммитов

В коммитах используется `Тип(scope):` префикс, взятый из истории проекта. Scope необязателен и обозначает затронутую область (`ui`, `api`, название функции, название модуля).

| Префикс         | Используется для                           | Реальный пример из репозитория                                                         |
| --------------- | ------------------------------------------ | -------------------------------------------------------------------------------------- |
| `Feat(...)`     | Новая возможность                          | `Feat(ui): общий селектор страны Globalping для MTR / задержки / цензуры`              |
| `Fix(...)`      | Исправление ошибки                         | `Fix(ui): согласовать проверку ввода MAC с backend (ровно 12 шестнадцатеричных цифр)`  |
| `Refactor(...)` | Реструктуризация, без изменения поведения  | `Refactor(country-name): заменить вручную поддерживаемую таблицу на Intl.DisplayNames` |
| `Perf(...)`     | Работа над производительностью             | `Perf(frontend): загружать лениво только активную локаль интерфейса`                   |
| `Style(...)`    | Визуальная доработка или правка текста     | `Style(toggle): высококонтрастное состояние нажатия для базовых переключателей`        |
| `Chore(...)`    | Инструменты, зависимости, служебные правки | `Chore: упростить сопоставление путей jsconfig`                                        |

Пишите сообщения на английском, в повелительном наклонении, и держите одну задачу на коммит.

## Правило i18n

Языки, которые предлагает интерфейс, сведены в один центральный реестр, `common/locale-registry.js`. У каждого есть `status`: **`full`** локаль — это та, куда обязательно должен попадать любой change текста, а **`beta`** одна может выходить с неполным пакетом и откатываться на английский. Сам реестр — это текущий список того, какая локаль имеет какой статус.

{% hint style="danger" %}
Любое изменение, которое затрагивает видимый пользователю текст, должно обновлять **каждый `full` файл локали в том же коммите** — включая `frontend/data/changelog.json` записи. `tests/locale-packs.test.js` и `tests/changelog.test.js` это обеспечивается автоматически, поэтому неполный перевод проваливается `pnpm check`.
{% endhint %}

Если вы не уверены, что можете правильно написать локаль, всё равно добавьте ключ во все файлы, сделав лучший возможный вариант, и укажите это в pull request. Подробности: [i18n](/developer/ru/development/i18n.md).

**Добавление нового языка — это другая, гораздо меньшая задача** — только фронтенд, каркас создаётся с помощью `pnpm i18n-new <code>`, а частичный перевод — желанный первый PR. См. [Перевод MyIP](/developer/ru/contributing/translating.md).

## Тесты

Невизуальная логика, которая может работать без сетевого запроса — чистые функции, валидаторы, преобразования, composables с подменяемыми входными данными — поставляется со спецификацией в `tests/` в том же изменении. Рендеринг интерфейса, реальное сетевое поведение и browser API не входят в область применения. См. [Тестирование](/developer/ru/development/testing.md).

## Ревью кода

Сопровождающий просматривает каждый pull request. Ожидайте вопросов, запросов на изменения или обсуждения подхода перед слиянием. Это нормально, а не отказ.

Отправляйте последующие коммиты в ту же ветку — pull request обновляется автоматически. Если ваше изменение визуальное и его нельзя проверить в headless-режиме, скажите об этом и приложите скриншот или короткую запись.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ipcheck.ing/developer/ru/contributing/how-to-contribute.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.