# Вклад в Gentoo-оверлей Precizer

[English translation](CONTRIBUTING.md)

Этот документ описывает добавление новых версий Precizer, обновление `Manifest` и проверку полного жизненного цикла пакета в Gentoo

## Добавление новой версии

Подготовка новой версии состоит из следующих этапов

1. В каталоге `app-forensics/precizer/` создаётся ebuild с именем `precizer-X.Y.Z.ebuild`, где `X.Y.Z` совпадает с версией исходного архива Precizer
2. Сборочные цели, тестовые цели, зависимости и путь к устанавливаемому файлу сверяются с соответствующим выпуском основного проекта
3. `Manifest` вручную не редактируется, поскольку автоматическая сборка пересчитывает его для всех находящихся в каталоге ebuild
4. После подготовки ebuild из корня репозитория выполняется `make`
5. После успешной проверки набор изменений будет содержать новый или изменённый ebuild и актуализированный `app-forensics/precizer/Manifest`

Публикация изменений в удалённый репозиторий перед проверкой не требуется. Автоматизация использует текущие локальные файлы из `app-forensics/precizer/`

## Автоматическая проверка пакета в Docker

Для запуска нужны GNU Make, Docker и сеть. По умолчанию используется образ `gentoo/stage3:latest` и создаётся временный контейнер `precizer-gentoo-overlay`

Из корня репозитория выполнить

```sh
make
```

Цель по умолчанию `all` запускает цель `docker-gentoo`. Внутри Docker выполняются подготовка локальной рабочей копии, обновление `Manifest`, два цикла проверки локального пакета и два цикла проверки опубликованного пакета через каталог Gentoo

Проверка состоит из следующих этапов

1. Оставшийся проектный контейнер безопасно удаляется, образ Gentoo загружается или обновляется, затем создаётся новый контейнер с меткой принадлежности к текущему сценарию
2. В контейнере синхронизируется основной репозиторий Gentoo и устанавливаются Git вместе с `app-eselect/eselect-repository`
3. Оверлей подключается альтернативным ручным способом через `repos.conf` и синхронизируется с исходным Git-репозиторием
4. Каталог пакета заменяется содержимым локального `app-forensics/precizer/`, поэтому первый контур проверяет текущую рабочую копию
5. Контейнерный кэш distfiles полностью очищается, исходные архивы для каждого локального ebuild заново загружаются по указанным в нём URL, после чего Portage принудительно пересчитывает общий `Manifest`
6. Непустой `Manifest` копируется из контейнера во временный файл рядом с локальным `Manifest` и затем атомарно заменяет `app-forensics/precizer/Manifest`
7. Последняя локальная версия пакета собирается из исходников без запуска тестов и без использования бинарного пакета, устанавливается, проходит smoke-test `precizer --version` без явного пути, удаляется через Portage и проверяется на отсутствие команды в `PATH`
8. Та же локальная версия повторно собирается из исходников с `USE=test` и `FEATURES=test`, проходит тестовую фазу ebuild, устанавливается, снова проходит smoke-test, удаляется через Portage и повторно проверяется на отсутствие команды в `PATH`
9. Ручная конфигурация и синхронизированный каталог полностью удаляются, после чего проверяется отсутствие репозитория `precizer` в Portage
10. Оверлей заново подключается через `eselect repository enable precizer` из поддерживаемого Gentoo каталога и синхронизируется командой `emaint sync -r precizer`
11. Для опубликованного checkout проверяются путь, имя репозитория, origin, непустой `Manifest` и наличие ebuild. Локальные файлы в этот checkout не копируются, а его `Manifest` не пересчитывается
12. Кэш distfiles снова очищается, затем последняя опубликованная версия собирается, устанавливается, проходит smoke-test, удаляется и проверяется на отсутствие команды в `PATH`
13. Опубликованная версия повторно проходит тот же цикл с `USE=test` и `FEATURES=test`
14. Команда `eselect repository remove precizer` удаляет подключённые через каталог Gentoo конфигурацию и checkout, после чего проверяется их отсутствие
15. После успешного завершения, ошибки или обрабатываемого сигнала выполняется автоматическая попытка удалить временный контейнер

Очистка distfiles происходит только внутри временного контейнера. В локальном контуре она позволяет обнаружить изменение исходного архива до публикации релиза, а в контуре через каталог Gentoo — независимо загрузить архивы, проверяемые опубликованным `Manifest`. В рабочей копии автоматизация изменяет только `app-forensics/precizer/Manifest`

Любая ошибка обязательного этапа приводит к ненулевому статусу `make`. Локальный `Manifest` копируется на хост до всех сборочных проверок, поэтому успешно пересчитанные хеши сохраняются даже при последующей ошибке локального контура или контура через каталог Gentoo

## Ручная установка с запуском тестов

Для разовой проверки ebuild в уже подключённом оверлее используются USE-флаг `test` и Portage feature `test`

```sh
USE="test" FEATURES="test" emerge --ask app-forensics/precizer
precizer --version
```

`USE=test` разрешает тестовую фазу для пакета `app-forensics/precizer`, а `FEATURES=test` сообщает Portage, что тесты должны быть выполнены во время сборки

## Очистка тестового контейнера

Обычно временный контейнер удаляется автоматическим обработчиком очистки. Ошибка очистки не заменяет результат основной проверки, поэтому контейнер может остаться, если Docker в этот момент недоступен. После принудительной остановки без выполнения обработчика, например через `SIGKILL` или перезапуск Docker, оставшийся контейнер можно удалить с помощью `make clean`

Из корня репозитория выполнить

```sh
make clean
```

`make clean` является алиасом цели `docker-clean-gentoo`. Команда ищет контейнер с настроенным именем, проверяет метку принадлежности и удаляет его только после подтверждения принадлежности этому проекту. Контейнер с тем же именем, но без ожидаемой метки, остаётся без изменений

При отсутствии контейнера команда успешно завершается без изменений. Docker-образ, ebuild-файлы и `Manifest` не удаляются

## Структура репозитория

```text
Makefile
scripts/
    docker-gentoo.sh
    verify-precizer-ebuild.sh
app-forensics/precizer/
metadata/
profiles/
```

`Makefile` предоставляет цели автоматической проверки и очистки. `scripts/docker-gentoo.sh` управляет контейнером и возвращает обновлённый `Manifest` в рабочую копию. `scripts/verify-precizer-ebuild.sh` копируется в контейнер, подготавливает оверлей и выполняет проверку пакета. `app-forensics/precizer/` содержит ebuild и metadata пакета. `metadata/layout.conf` сообщает Portage, что оверлей наследует основной репозиторий Gentoo. `profiles/repo_name` задаёт имя репозитория `precizer`