Участие

Существует множество способов внести свой вклад в проект OneFuzz: регистрация ошибок, отправка pull-запросов, отчет о проблемах и создание предложений.

Пожалуйста, ознакомьтесь с нашими значками проекта.

Отчет о проблемах безопасности

Пожалуйста, не сообщайте о проблемах безопасности через публичные issues GitHub. Вместо этого сообщите об этом в Microsoft Security Response Center (MSRC). Дополнительную информацию см. в SECURITY.md.

Перед тем как начать, создайте issue

Пожалуйста, следуйте этой простой правиле, чтобы помочь нам избежать ненужных потерь времени и разочарований, и обеспечить эффективное и эффективное использование времени всех участников - вашего, нашего и других членов сообщества:

👉 Если у вас есть вопрос, вы считаете, что обнаружили проблему, хотите предложить новую функцию и т. д., то найдите/создайте issue ДО начала работы по устранению/реализации этой проблемы.

Поиск существующих проблем

Перед созданием нового issue, сначала поищите существующие открытые и закрытые issues: Этот проект развивается быстро! Вероятно, кто-то уже столкнулся с той же проблемой, и кто-то может работать над или уже внедрил решение!

Если нет существующего item, описывающего вашу проблему/функцию, отлично - создайте новый issue:### Создание нового Issue

• Не знаете, сообщаете ли вы о проблеме или просите новую функцию? Создайте issue
• У вас есть вопрос, который вы не видите в документах, видео и т.д.? Создайте issue
• Хотите узнать, планируем ли мы внедрить определенную функцию? Создайте issue
• У вас есть отличная идея для новой функции? Создайте issue/запрос/идею
• Нашли существующий issue, описывающий вашу проблему? Отлично — проголосуйте и добавьте дополнительные комментарии / информацию / шаги по воспроизведению и т.д.

Когда вы нажимаете "Новый Issue", выберите тип issue, наиболее соответствующий тому, что вы хотите сообщить/спросить/запросить.

Заполните шаблонЗаполните запрошенную информацию в шаблоне issue, предоставляя столько информации, сколько возможно. Чем больше информации вы предоставите, тем вероятнее, что ваш issue/запрос будет понят и реализован. Полезная информация включает:

• Какие инструменты и приложения вы используете (например, VS 2019, VSCode и т.д.)
• Не предполагайте, что мы эксперты в настройке ВАШЕЙ среды, и не предполагайте, что мы эксперты в <ваш дистрибутив/инструмент выбора>. Обучите нас, как нам помочь!
• Мы ЛЮБИМ детальные шаги воспроизведения! Какие шаги нам нужно предпринять, чтобы воспроизвести проблему? Предположим, что мы любим читать шаги воспроизведения. Сколько бы ни было подробностей, вы можете выдержать, скорее всего, будет всего лишь достаточно для нас.
• Предпочтительно использовать текст сообщений об ошибках, где это возможно, или скриншоты ошибок, если текст не может быть захвачен
• Мы ОЧЕНЬ предпочитаем текстовые скрипты командной строки, а не скриншоты скриптов командной строки.> 👉 Если у вас нет дополнительной информации/контекста для добавления, но вы

хотите указать, что вы затронуты данной проблемой, то поставьте лайк оригинальному сообщению, нажав на кнопку [+😊] и на значок 👍 (+1). Таким образом мы сможем измерить значимость проблемы.## Внесение вклада в исправление проблем / реализацию функций

Для тех, кто готов и хочет помочь исправить проблемы и/или реализовать функции...

Нужно ли писать спецификацию?

Некоторые проблемы/функции могут быть легко описаны и поняты. В таких случаях, если команда одобрила ваш подход, пропустите к разделу "Fork, Branch, и Create your PR" ниже.

Мелкие проблемы, которые не требуют спецификации, будут помечены как Issue-Bug или Issue-Task.

Однако, некоторые проблемы/функции требуют тщательного анализа и формального проектирования перед реализацией. В таких случаях мы будем просить написать спецификацию, а связанную с ней проблему пометить как Issue-Feature.

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

Спецификации будут управляться аналогично вкладам в код, поэтому следуйте инструкциям "Fork, Branch и Create your PR" ниже.

Писание / Вклад в спецификацию

Чтобы написать/внести вклад в спецификацию: fork, branch и commit через PRs, как вы бы делали это с любыми изменениями кода.Спецификации пишутся в markdown, хранятся в папке \doc\spec и названы [issue id] - [описание спецификации].md.

👉 Важно следовать шаблонам спецификаций и заполнить запрошенную информацию. Доступные шаблоны спецификаций помогут убедиться, что спецификации содержат минимальную информацию и решения, необходимые для начала разработки. В частности, спецификации требуют подтверждения того, что вы уже обсудили проблему/идею с командой в сообщении и что вы предоставили ID сообщения для ссылки.

Участники команды будут рады помочь в проверке спецификаций и помочь довести их до завершения.

Помощь нужна

После того как команда одобрила задачу/спек, можно приступить к разработке. Если сразу нет доступных разработчиков, спек можно приостановить, ожидая, пока разработчик возьмется за работу. Задачи приостановленных спеков будут помечены меткой "Help Wanted" (Помощь нужна). Чтобы найти список разработочных возможностей, ожидающих участия разработчиков, посетите раздел Issues (Задачи) и отфильтруйте по метке Help-Wanted.

Разработка

Создание форка, клонирование, создание ветки и отправка PR

После того как вы обсудили свой предлагаемый функционал/фикс/и т.д. с членом команды, и вы согласовали подход или спецификацию, которая была написана и одобрена, настало время начать разработку:1. Создайте форк репозитория, если вы еще этого не сделали.

1. Клонируйте свой форк локально.
2. Создайте и отправьте ветку с новыми функциями.
3. Создайте черновой Pull Request (PR)
4. Работайте над своими изменениями.
5. Постарайтесь следовать существующему стилю связанного кода как можно ближе.

Специфика Python

1. Предоставьте как можно больше контекста при определении типов переменных. Например, Dict[UUID, int] лучше, чем Any.
2. Для сложного набора данных рассмотрите использование объектов (например, pydantic типизированных классов данных) вместо вложенных Dicts, Tuples или Lists.

Локальные условия сборки

OneFuzz состоит из нескольких компонентов и работает на Linux и Windows:

• Rust (последняя стабильная версия)
• Python (не менее 3.7 или более поздняя версия)
• Azure Functions Core Tools (последняя версия 4.x)

Хотя локальная сборка возможна для каждого компонента системы, новые участники могут найти автоматическую сборку для PR полезной.

Получение исходного кода

Сначала создайте форк репозитория OneFuzz, чтобы вы могли отправить pull request. Затем клонируйте свой форк локально:

git clone https://github.com/<<<ваш-github-аккаунт>>>/onefuzz.git
```Иногда вам потребуется объединить изменения из основного репозитория (официального репозитория кода) с вашим форком.

```bash
cd onefuzz
git checkout main
git pull https://github.com/microsoft/onefuzz.git main

Управляйте любыми конфликтами слияния, коммитируйте их и затем отправляйте их в ваш форк.

👉 Репозиторий microsoft/onefuzz содержит GitHub Actions, которые автоматически собирают OneFuzz и сортируют компоненты во время разработки. Если вы не хотите, чтобы эти действия выполнялись на вашем форке, вы можете отключить Actions для вашего форка через https://github.com/YOUR_USERNAME/onefuzz/settings/actions.

Развертывание из сборки

Эти инструкции предполагают наличие рабочей установки Python 3.7 (или более поздней версии) и активированной сессии Azure CLI.

1. Скачайте release-artifacts из вашего сборочного процесса CICD.
2. Создайте новую директорию для релизных артефактов.
3. Распакуйте release-artifacts.zip в эту новую директорию.
4. Распакуйте получившийся zip-файл, который начинается с onefuzz-deployment.
5. Настройте виртуальное окружение Python. Пример: python3 -m venv onefuzz-deploy-venv
6. Активируйте виртуальное окружение. Пример: . onefuzz-deploy-venv/bin/activate
7. Установите python-wheel. Пример: pip install wheel
8. Установите предварительные требования для развертывания. Пример: pip install -r requirements.txt
9. Запустите скрипт развертывания: Пример: python deploy.py ${REGION} ${GROUP} ${INSTANCE} ${OWNER}### Обзор кода

Когда вы хотите, чтобы команда взглянула на вашу работу (даже если она ещё не завершена), отметьте ваш запрос на внесение изменений как 'Готов к обзору', чтобы команда могла просмотреть вашу работу, оставить комментарии, предложения и запросы на изменения. Это может занять несколько циклов, но в конечном итоге результат будет надёжным, проверяемым и соответствующим кодом, безопасным для слияния.

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

Слияние

Как только ваш код будет проверен и одобрен необходимым количеством членов команды, он будет слит в ветку master. После слияния ваш запрос на внесение изменений будет автоматически закрыт.

Спасибо

Благодарим вас за ваш вклад заранее!