# Исходники платформенных пакетов

## Назначение

`packages/**` хранит checkout пакетов, объявленных в `.gitmodules`.

Пакетом может быть платформенный или пользовательский пакет из каталога. Доступность и права на пакет проверяет платформа до checkout.

Корневое разделение такое:

- `docs/**` — активная документация и источники внешних документационных репозиториев через `docs/external/**`;
- `packages/**` — пакеты, подключённые к текущему проекту или установке.

Так документы остаются в `docs`, а пакеты — рядом в `packages`, без смешивания двух разных типов содержимого.

## Подключённые источники

Актуальный перечень подключённых пакетов смотреть в `.gitmodules` и в каталогах внутри `packages/**`.

## Что держать как submodule, а что нет

- Источник пакета объявляется в `.gitmodules`, а конкретная версия фиксируется gitlink в основном репозитории.
- Пользовательские форки и downstream-инсталляции должны иметь workflow, который удаляет магазин, сайт и необязательные пакеты, не предназначенные для конкретного репозитория.

## Как подключать вручную

```bash
git -c submodule.<name>.update=checkout submodule update --init packages/<package>
```

Для закрытых пакетов перед checkout нужен подтверждённый доступ. Если доступа нет, платформа должна явно показать ошибку прав, а не подменять пакет локальной копией.

## Как обновлять ссылку

1. Внести изменения в целевом внешнем репозитории в отдельной ветке.
2. Создать и смержить PR в этом внешнем репозитории.
3. В `kodex` обновить gitlink:

```bash
git -C packages/<package> pull --ff-only
git add packages/<package>
```

4. В том же PR обновить документацию `kodex`, если изменилась каноника или инструкции.
