Гайд по вкладам проекта CBL-Mariner

Оглавление

Для удобства воспользуйтесь автоматически сгенерированным оглавлением, которое создает GitHub. Чтобы его открыть, выберите значок меню со стрелками в верхней части страницы.

Лицензионное соглашение для вкладов

Этот проект приветствует вклады и предложения участников. Большинство вкладов требуют от вас подписания лицензионного соглашения (CLA), которое подтверждает ваше право и фактическое предоставление нам прав использовать ваш вклад. Подробнее см. https://cla.microsoft.com.

Когда вы отправляете запрос на слияние (pull request), бот CLA будет автоматически проверять, требуется ли вам подписать CLA, и помечать ваш запрос соответствующими метками (например, метка, комментарий). Просто следуйте указаниям бота. Вам потребуется сделать это всего один раз для всех репозиториев, использующих наш CLA.

Этот проект придерживается кодекса поведения Microsoft для открытых источников. Для получения дополнительной информации см. Faq по кодексу поведения или свяжитесь с нами по адресу opencode@microsoft.com с любыми дополнительными вопросами или замечаниями.

Уязвимости безопасности

БезопасностьMicrosoft уделяет большое внимание безопасности наших продуктов和服务，包括我们通过GitHub管理的所有源代码存储库，例如Microsoft，Azure，DotNet，AspNet，Xamarin和我们的GitHub组织。

翻译后的文本： Microsoft уделяет большое внимание безопасности наших продуктов и услуг, что включает все репозитории исходного кода, управляемые через наши организации GitHub, такие как Microsoft, Azure, DotNet, AspNet, Xamarin и наши организации GitHub.Если вы считаете, что нашли уязвимость безопасности в любом репозитории, принадлежащем Microsoft, который соответствует определению Microsoft определения уязвимости безопасности, пожалуйста, сообщите об этом, как указано ниже.

Отчет об уязвимостях безопасности

Пожалуйста, не сообщайте об уязвимостях безопасности через публичные issues GitHub. Вместо этого отправьте их в Центр отклика безопасности Microsoft (MSRC) по адресу https://msrc.microsoft.com/create-report.

Если вы предпочитаете отправить данные без входа в систему, отправьте электронное письмо на secure@microsoft.com. В случае возможности зашифруйте ваше сообщение с помощью нашего ключа PGP; пожалуйста, скачайте его со страницы ключей PGP Центра отклика безопасности Microsoft.

Вы должны получить ответ в течение 24 часов. Если по какой-либо причине этого не произойдет, пожалуйста, свяжитесь с нами повторно по электронной почте, чтобы убедиться, что мы получили ваш первоначальный запрос. Дополнительная информация доступна по адресу microsoft.com/msrc.

Пожалуйста, предоставьте запрошенную информацию ниже (все, что возможно), чтобы помочь нам лучше понять природу и масштаб возможной проблемы:* Тип проблемы (например, переполнение буферного окна, внедрение SQL, кросс-сайт скриптинг и т.д.)

• Полные пути исходных файлов, связанных с проявлением проблемы
• Расположение затронутого исходного кода (тэг/ветка/коммит или прямой URL)
• Любое специальное конфигурирование, необходимое для воспроизведения проблемы
• Пошаговая инструкция для воспроизведения проблемы
• Пример доказательства или код эксплоита (если это возможно)
• Воздействие проблемы, включая то, как злоумышленник может ею воспользоваться

Эта информация поможет нам быстрее рассмотреть ваш отчёт.

Если вы сообщаете о проблеме в рамках программы вознаграждения за уязвимости, более полные отчёты могут способствовать увеличению размера вознаграждения. Пожалуйста, посетите нашу страницу Программы вознаграждения за уязвимости Microsoft для получения дополнительной информации о наших активных программах.

Предпочтительные языки

Мы предпочитаем все коммуникации на английском языке.

Политика

Microsoft следует принципу координированного раскрытия уязвимостей.## Разработка для CBL-Mariner

При начале работы с CBL-Mariner используйте репозиторий CBL-MarinerTutorials. Этот репозиторий помогает разработчикам использовать инструменты CBL-Mariner для настройки или добавления новых пакетов или образов. После того как вы подтвердите, что ваше изменение успешно собирается и работает так, как ожидалось, рассмотрите возможность его добавления в основной репозиторий, CBL-Mariner.

Для получения руководства и краткого руководства воспользуйтесь нашими материалами, а также инструкциями по сборке для подробного обзора процесса сборки в CBL-Mariner. При внесении вклада следует придерживаться правил отправки pull request.

ПакетыПакеты CBL-Mariner находятся либо в SPECS, либо в SPECS-EXTENDED. Пакеты CBL-Mariner, расположенные в директории SPECS, имеют полную поддержку и охват с своевременным обслуживанием CVE. Пакеты в SPECS-EXTENDED предназначены только для экспериментов или концептов. SPECS-EXTENDED может использоваться как зона тестирования для пакетов с возможностью перехода в SPECS.

Когда вы планируете переместить пакет из SPECS-EXTENDED в SPECS, создайте issue GitHub, акцентируя внимание на значимости пакета, и убедитесь, что следующие шаги выполнены для связанных PR:1. Увеличьте значение Release в спецификации.

1. Добавьте записи в журнал изменений "Пакет перемещён из SPECS-EXTENDED в SPECS" и "Лицензия проверена".
2. Добавьте раздел %check в спецификацию, если он ещё не существует, и убедитесь, что он проходит проверку.
3. Убедитесь, что спецификация свободна от ссылок, макросов, комментариев и т.д., применимых только к другим дистрибутивам.
4. Выполните проверочный список PR.
5. Прохождение проверок GitHub.### Инструментарий

Мы приветствуем улучшения инструментария. При внесении изменений в инструментарий, пожалуйста, придерживайтесь формата golang, описанного в пакете fmt. Для форматирования используйте этот пакет, запустив команду make go-tidy-all в вашем инструментарии CBL-Mariner. Для руководства по сборке с помощью инструментария, обратитесь к нашим инструкциям по сборке.

Документация

Мы приветствуем улучшения документации. Последняя документация доступна по адресу toolkit/docs.

Правила создания pull request

Пожалуйста, направляйте pull request на желаемую ветку развития. Изменения для 2.0 следует направлять на ветку main. Изменения для 1.0 следует направлять на ветку 1.0-dev.

Структура ветвей

Обзор того, как структурированы ветви, представлен ниже.

Заголовки PR должны начинаться с действия.

- Добавить <пакет>
- Обновить версию выпуска для октябрьского обновления
- Изменить то, что вы изменили
- Исправить <то, что было исправлено> <причина исправления>
- Устранить <пакет> для исправления CVE-XXXX-YYYY, CVE-XXXX-YYYY...
- Обновить <пакет> до версии vvvv для исправления CVE-XXXX-YYYY...
- Удалить <пакет> <причина удаления>

Пожалуйста, избегайте заголовков такого типа:

- пакет: <что бы вы ни делали с пакетом>
- CVE-XXXX-YYYY (не указывая, какой пакет был исправлен или обновлен)
- [1.0] (добавление информации о ветке или другого контекста)

Проверочный список PR

Когда создаете свой PR, убедитесь, что выполнены следующие условия:

• Инструментная цепочка успешно перестроена (или изменения не были сделаны). Это применимо только если вы изменили какие-либо пакеты в MANIFEST файлах инструментной цепочки. Конкретно, toolchain_x86_64.txt и toolchain_aarch64.txt. Для руководства по сборке инструментной цепочки см. наши руководства по сборке.

• MANIFEST файлы инструментной цепочки / рабочего пакета актуальны (версии совпадают с последними версиями пакетов в SPEC файлах). MANIFEST файлы следующие:

  • toolchain_x86_64.txt
  • toolchain_aarch64.txt
  • pkggen_core_x86_64.txt
  • pkggen_core_aarch64.txt* Любые обновленные пакеты успешно собираются (или пакеты не были изменены). Для руководства по сборке пакетов см. наши руководства по сборке. Убедитесь, что пакет находится в соответствующей папке.*

Пакеты, зависящие от модифицированных статических компонентов в этом запросе (Golang, пакеты *-static и т.д.), имеют увеличенный тег Release. Зависимыми пакетами являются те, которые содержат BuildRequires на пакет, который вы обновляете, и создают статические ссылки с вашего пакета. Это может быть сложно определить только на основе файлов spec и может потребовать рассмотрения команд make в зависимых пакетах или консультации с разработчиком CBL-Mariner.

• Тесты пакетов (%check раздел) были проверены с помощью RUN_CHECK=y для существующих файлов SPEC, или добавлены в новые файлы SPEC. При выполнении раздела тестов результаты не должны привести к провалу сборки. Проверьте логи для результатов этого раздела.** Все источники пакетов доступны. Источники либо находятся на сервере источников, либо в локальной папке SPECS (SPECS/<пакет>/SOURCES или SPECS/<пакет>). Хотя возможно сборка пакетов со всеми источниками внутри репозитория, наша политика обычно требует сжатия источников и размещения их на сервере источников. Загрузка на сервер источников может быть выполнена только разработчиком CBL-Mariner. Пожалуйста, запрашивайте помощь в вашем запросе для загрузки ваших источников на сервер источников. Для проверки сервера источников см. [https://azurelinuxsrcstorage.blob.core.windows.net/sources/core/<источник tar>].* Файлы cgmanifest актуальны и отсортированы алфавитически. Файлы cgmanifest используются для записи всех источников пакетов. Они включают следующие файлы:

  • ./cgmanifest.json
  • ./toolkit/tools/cgmanifest.json
  • ./toolkit/scripts/toolchain/cgmanifest.json
  • .github/workflows/cgmanifest.json

  Для проверки выполните следующее в контейнере CBL-Mariner или Ubuntu >= 22.04

  .github/workflows/validate-cg-manifest.sh SPECS/<package name>/<package-name>.spec

• Файлы LICENSE-MAP актуальны. Эти файлы указывают, какие лицензии используются пакетами CBL-Mariner и где эти пакеты могут быть получены. Лицензионные файлы включают следующие файлы:

  • ./SPECS/LICENSES-AND-NOTICES/data/licenses.json
  • ./SPECS/LICENSES-AND-NOTICES/LICENSES-MAP.md

  Это можно проверить, выполнив

  python3 ./toolkit/scripts/license_map.py \
  ./SPECS/LICENSES-AND-NOTICES/data/licenses.json \
  ./SPECS/LICENSES-AND-NOTICES/LICENSES-MAP.md \
  ./SPECS \
  ./SPECS-EXTENDED \
  ./SPECS-SIGNED

• Все исходные файлы содержат актуальные хэш-суммы в файлах *.signatures.json. Эти хэши генерируются с помощью sha256sum. Вы также можете использовать средства сборки для автоматического обновления этих хэшей.

  cd toolkit
  sudo make input-srpms REBUILD_TOOLS=y SRPM_FILE_SIGNATURE_HANDLING=update

• Если вы изменили Go-инструменты, убедитесь, что форматирование соответствует стандартам Go, а тесты все еще проходят.

  cd toolkit
  # исправление форматирования
  sudo make go-tidy-all
  # проверка тестов
  sudo make go-test-coverage

• Документация была обновлена, чтобы соответствовать изменениям в системе сборки. См. toolkit/docs.## Проблемы

Если проблема связана с безопасностью, пожалуйста, используйте руководство по безопасности выше. В противном случае, пожалуйста, используйте страницу issues проекта CBL-Mariner для отслеживания ошибок.