> 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).

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

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 с меткой `good first issue`.

## Процесс

{% stepper %}
{% step %}

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

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

{% step %}

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

Сделайте fork репозитория, затем создайте свою ветку от **`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` получает только релизные слияния из `dev` ветки. Pull request, нацеленный на `main` попросят перенаправить.
{% endhint %}

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

## Правила pull request'ов

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

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

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

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

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

## Правило i18n

MyIP поставляется в четырёх локалях: `en`, `zh`, `fr`, `ru`.

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

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

## Тесты

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

## Ревью кода

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

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


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.