Вклад в проект

Прежде чем вносить свой вклад в этот проект, пожалуйста, ознакомьтесь со следующими инструкциями:

• Как задать вопрос?

• Как сообщить об ошибке?

• Как предложить новую функцию?

• Как создать запрос на включение изменений (Pull Request)?

Как задать вопрос?

Если у вас есть вопросы по использованию библиотеки, сначала ознакомьтесь с документацией по разработке, предоставленной этим проектом, и попробуйте поискать в списке проблем.

Если вы всё ещё не можете найти решение, создайте новую проблему.

Как сообщить об ошибке?

Вы можете указать на уязвимости в исходном коде, проблемы с выполнением или ошибки в документации, отправив проблему. Конечно, если вы можете предоставить исправление в виде PR, это будет ещё лучше.

При отправке проблемы, пожалуйста, включите следующую информацию:

1. Простое описание проблемы.

2. Среда выполнения, в которой возникла проблема (например, версия операционной системы, версия .NET Runtime, используемая версия этой библиотеки и т. д.).

3. Код, связанный с проблемой, или минимальный проект для воспроизведения проблемы (можно загрузить на хостинги кода или использовать GitHub Gist).

4. Сообщение об ошибке и трассировка стека при возникновении ошибки.

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

Как предложить новую функцию?

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

Перед отправкой проблемы обратите внимание на следующие моменты:

1. Эта библиотека фокусируется на упаковке API и больше ориентирована на SDK, а не на полноценный веб-фреймворк, поэтому не предлагайте функции, которые должны быть реализованы на уровне фреймворка.

2. Библиотека предоставляет множество расширяемых интерфейсов, поэтому оцените, можно ли реализовать желаемую функцию без изменения проекта.

3. Стабильность имеет решающее значение, поэтому будьте осторожны с предложениями функций, требующих значительных разрушительных изменений.

Как создать запрос на включение изменений?

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

1. Проверьте, соответствует ли новый код существующему стилю кода и стандартам именования проекта:

   • Запрещено: исходный код не должен содержать последовательных пустых строк, между полями, атрибутами, методами должна быть одна пустая строка;
   • Обязательно: структура каталогов должна соответствовать существующей структуре каталогов;
   • Обязательно: классы (Class), атрибуты (Property) и методы (Method) должны называться с использованием стиля CamelCase, например, Class, Property и Method, соответственно, на основе существующих моделей;
   • Обязательно: при предоставлении новых API следует следовать способу именования моделей API, описанному в документации по разработке, на основе существующих моделей;
   • Обязательно: для общедоступных классов, атрибутов и методов должны предоставляться XML комментарии, как в существующих комментариях;
   • Обязательно: в моделях API массивы должны объявляться как IList для типов коллекций, а в ответных моделях — как массивы, на основе существующих моделей;
   • Обязательно: типы подклассов должны быть включены в один открытый вложенный статический класс с именем Types, на основе существующих моделей;
   • Обязательно: JsonConverters для моделей API должны быть вложены в один внутренний вложенный статический класс с именем Converters, на основе существующих моделей;
   • Обязательно: ссылочные типы, не являющиеся пустыми, должны иметь значения по умолчанию для соответствующих типов в запросах (для строковых типов — string.Empty), а в ответах — default!, на основе существующих моделей;
   • Рекомендуется: ссылочные типы, которые могут быть нулевыми, должны быть объявлены как class? (где class — конкретное имя класса), на основе существующих моделей;
   • Обязательно: атрибуты в моделях API, если они сериализуются в сокращённой форме, должны быть восстановлены до их полных форм (например, img → Image, thumb → Thumbnail, avg → Average, cid → CategoryId и т.д.), но некоторые конкретные термины могут не требовать этого (например, Id, Http, Url, Cgi и т.д.);
   • Рекомендуется: атрибуты в моделях API, если их сериализованное значение равно 0 / 1 и не может быть увеличено в будущем, могут быть объявлены как тип bool;
   • Рекомендуется: атрибуты в моделях API, представляющие даты и время в формате строки, могут быть объявлены как тип DateTimeOffset;
   • Рекомендуется: атрибуты в моделях API, представляющие данные в формате JSON, могут быть объявлены с соответствующими типами и JsonConverters, вместо объявления как string напрямую;
   • Рекомендуется: логические атрибуты в моделях API могут иметь имена, начинающиеся с Is или Has;
   • Рекомендуется: атрибуты, представляющие временные метки, могут иметь окончания, такие как Timestamp;
   • другие аспекты см. в официальном руководстве Microsoft по проектированию фреймворков.

2. Напишите новые модульные тесты и запустите существующие модульные тесты, чтобы убедиться, что ваши изменения работают правильно:

   • Запрещено: обратите внимание на файл csproj проекта модульных тестов, добавление новых файлов может привести к изменению его содержимого, не добавляйте эти изменения в git;
   • Запрещено: обратите внимание на файл appsettings.json проекта модульных тестов, после клонирования репозитория выполните команду git update-index --assume-unchanged, чтобы избежать фиксации конфиденциальной информации в git;
   • Обязательно: тесты стиля кода должны пройти успешно, и должны быть предоставлены примеры моделей API;
   • Обязательно: если это не интерфейс API, который был изменён (например, служебные классы), должны быть предоставлены тестовые случаи;
   • Обязательно: каталог и имена файлов примеров моделей API в проекте модульных тестов должны соответствовать исходному проекту, на основе существующих примеров;
   • Рекомендуется: по возможности следуйте примерам, предоставленным в официальной документации ByteDance.

3. Сформируйте логический комментарий к коммиту:

   • Обязательно: формат комментария к коммиту должен быть <type>(<scope>): <subject>.

   • Обязательно: тип в комментарии к коммиту может быть:

     • feat: новая функция или изменение существующей функции;
     • fix: исправление ошибки или опечатки; — docs: изменение документации; — style: форматирование (без изменения содержания кода); — refactor: рефакторинг (изменение кода, но без влияния на существующую функциональность и без добавления новой функциональности); — test: связанное с тестированием; — chore: другое.

   • Обязательно: область действия в комментарии к коммиту может быть: — microapp: изменения, связанные с проектом SKIT.FlurlHttpClient.ByteDance.MicroApp; — douyinopen: изменения, связанные с проектом SKIT.FlurlHttpClient.ByteDance.DouyinOpen; — douyinshop: изменения, связанные с проектом SKIT.FlurlHttpClient.ByteDance.DouyinShop; — oceanengine: изменения, связанные с проектом SKIT.FlurlHttpClient.ByteDance.OceanEngine; — tiktok: изменения, связанные с проектом SKIT.FlurlHttpClient.ByteDance.TikTokGlobal; — tiktokshop: изменения, связанные с проектом SKIT.FlurlHttpClient.ByteDance.TikTokGlobalShop; — оставить пустым: не относится ни к одному из вышеперечисленных случаев.

   — Рекомендуется: комментарии к коммитам должны быть краткими и избегать внесения множества изменений, которые затем объединяются вместе, чтобы не усложнять поиск в будущем.

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

Поэтому этот проект строго ограничивает стандарты PR и имеет право давать обратную связь и рекомендации авторам PR, и только после того, как автор внесёт соответствующие изменения, PR будет одобрен и объединён. (Примечание: существующие комментарии к коммитам можно изменить с помощью команды git rebase.)

Кроме того, необходимо отметить, что после синхронизации с Gitee PR может потерять свои комментарии, если автор PR заботится об этом, рекомендуется отправлять PR только на GitHub.