English | Простой китайский

Вклад в код

Если у вас есть вопросы, пожалуйста, откройте issue, или отправьте pull request (PR).

Открытие issue

• Убедитесь, что вы выбрали правильный тип issue.
• Избегайте создания повторяющихся issues; прежде чем создавать новый issue, проверьте существующие.
• Включите конкретную цель в метках (по категориям смотрите Категоризация меток), заголовке или содержании.

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

Метки могут быть разделены на две категории: type и scope

• type: тип issue, такой как feature, bug, documentation, performance, support ...
• scope: область изменяемых файлов, такая как core: xx, plugin: xx, deps: xx

Общие объяснения меток

• support: если вопрос требует помощи от разработчиков, используйте метку support.
• bug: если вы нашли потенциальную ошибку, пометьте её как bug. После подтверждения она будет помечена как confirmed.
  • Такие проблемы будут иметь высший приоритет.
  • Если проблема влияет на работу онлайн-приложений, она будет помечена как critical, то есть имеет самый высокий приоритет.
  • Ошибки будут исправлены в минимальной версии, где это возможно. Например, если ошибка должна быть исправлена в 0.9.x, но текущая версия — 1.1.x, issue будет помечен как 0.9, 0.10, 1.0, 1.1.
• core: xx: указывает, что issue связан с ядром, например core: antx указывает на конфигурацию antx.
• plugin: xx: указывает, что issue связан с плагином, например deps: session указывает на плагин session.
• deps: xx: указывает, что issue связан с модулем зависимостей, например deps: egg-cors указывает на модуль egg-cors.
• chore: documentation: указывает на проблему с документацией, которая требует исправления.
• cbd: указывает на проблему, связанную с развертыванием сервера

Написание документации

Для всех новых функций должны быть созданы соответствующие документы, которые должны удовлетворять следующим требованиям:

• Должна быть предоставлена информация о нескольких аспектах: что это такое (что), почему это важно (почему), как это работает (как), можно акцентировать внимание на одном из этих аспектов.
• Часть как должна содержать подробные шаги выполнения, а также примеры кода, которые легко запустить.
• Все примеры кода должны быть помещены в eggjs/examples.
• Должны быть предоставлены необходимые ссылки, такие как процедуры запроса доступа, объяснение терминологии и ссылки на справочные материалы.
• Документация должна быть одновременно обновлена на английском и китайском языках, либо указано в pull request.

Получение и отправка кода

Получение кода

Перед тем как начать работу, нажмите кнопку "Fork" на странице Egg проекта на GitHub, чтобы склонировать проект в свой репозиторий, затем используйте git для клонирования кода на локальный компьютер. Будущее развитие будет происходить на этом локальном компьютере.

Установка зависимостей

Вы можете использовать встроенный менеджер пакетов Node.js npm для установки всех необходимых зависимостей, указанных в файле package.json.

npm i

Если вы сталкиваетесь с ошибками при установке зависимостей и ваша версия npm >=7.X, временным решением может быть использование ключа --legacy-peer-deps.

npm i --legacy-peer-deps

Пожалуйста, сообщите разработчикам об этой проблеме через Issues.

Отправка Pull Request

Если у вас есть права доступа к репозиторию и вы хотите сделать вклад в код, вы можете создать ветку, внести изменения и отправить pull request. Разработка команды egg будет проверять и объединять ваши изменения с основной веткой.

# Создайте новую ветку для разработки, название должно быть осмысленным
$ git checkout -b branch-name

# После завершения работы запустите тесты
$ npm test

# Если тесты прошли успешно, сделайте коммит
$ git add .
$ git commit -m "fix(role): role.use must xxx"
$ git push origin branch-name

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

1. Точка входа (обычно связана с issue или комментарием)
2. Причина обновления (не обязательно связано с issue, можно кратко описать причину)
3. Тестовые точки (можно указать тестовые файлы, не требуется детальное описание)
4. Особое внимание (например, обратная совместимость)

Стиль кода

Ваш стиль кода должен соответствовать ESLint. Вы можете проверить его локально с помощью команды $ npm run lint.

Примеры коммитов

Согласно стандарту Angular для коммитов, история коммитов должна быть понятной и удобной для чтения, а также должна автоматически генерировать changelog.

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

(1) type

Тип коммита, который может быть одним из следующих:

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

(2) scope

Область изменений (включая документацию, middleware, ядро, конфигурацию, плагины)

(3) subject

Описание одной строки того, что было сделано в данном коммите

(4) body

Дополнительное описание, причины, цели и т.д., может быть опущено.

(5) footer

• Если есть несовместимые изменения (Breaking Change), они должны быть описаны здесь
• Связь с другими issue, например Closes #1, Closes #2, #3
• Если есть новые или измененные функции, также следует связать документацию doc и egg-core с pull request, например eggjs/egg-core#123

Пример:

fix($compile): [BREAKING_CHANGE] несколько юнит-тестов для IE9
```Старые IEs сериализуют HTML с большими буквами, но IE9 нет...

Было бы лучше ожидать регистронезависимости, однако Jasmine не позволяет использовать регулярные выражения для ожидаемого вывода.


Изменение документации на eggjs/egg#123

Закрыто #392

BREAKING CHANGE:

  Брейк ин API `foo.bar`, теперь используется `foo.baz` вместо него


Для более подробной информации смотрите [документацию](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit).


### Английский язык

Основной текст на английском языке пишется согласно общим правилам английского языка. Однако заголовки имеют свои особенности:

- Первый буква каждого слова типа имя, глагол, местоимение, прилагательное, наречие должна быть заглавной, кроме предлогов, статей, союзов, восклицательных слов и частиц, которые начинаются строчной буквой. *Первая и последняя слова заголовка всегда начинаются с большой буквы, вне зависимости от их типа.*
- Для специальных названий (например, прямое упоминание переменной или имени плагина) используются обратные апострофы (тот, что находится под Esc на клавиатуре), и сохраняется исходное написание.
- Предлоги длиннее пяти букв начинаются с большой буквы, остальные — строчными.
- Если заголовок является важным предупреждением или специальным названием (например, HTTP методы: GET, POST, PUT, DELETE), все буквы могут быть заглавными (с осторожностью).
- Если заголовок представляет собой конструкцию субъект + объект (например, "Управление конфигурациями"), он обычно переводится как "объект + глагол-существительное" (Configuration Management) или "глагол-существительное + объект" (Managing Configuration).
- Если заголовок является полным английским предложением, он должен быть записан в соответствии с правилами английской пунктуации (например, каждый заголовок в разделе Часто задаваемые вопросы (FAQ) является полноценным английским предложением).

Для получения дополнительной информации см. [английское написание заголовков].


### Предварительный просмотр сгенерированной документации

Если вы изменили какой-либо `.md` файл в директории `docs` внутри директории `site`, вам потребуется перегенерировать документацию, чтобы видеть изменения.

Если вы используете версию Node.js между  Yöntemler: GET, POST, PUT, DELETE), tüm harfler büyük olabilir (dikkatli olarak).
- Eğer başlık bir özne + nesne yapısı (örnek: "Konfigürasyonları yönetme") ise genellikle "nesne + eylem-sıfat" (Configuration Management) veya "eylem-sıfat + nesne" (Managing Configuration) şeklinde çevrilir.
- Eğer başlık tam bir İngilizce cümle ise, İngilizce noktalama kurallarına göre yazılmalıdır (örnek: FAQ bölümündeki her başlık tam bir İngilizce cümle).

Daha fazla bilgi için lütfen [İngilizce Başlıkların Yazılması] belgesini inceleyin.


### Ön izlenme oluşturulan belge

Eğer `docs` klasörü içindeki `site` dizininize bir `.md` dosyası eklediniz veya değiştirdiniz, belgenizi yeniden oluşturmanız gerekecek ki değişiklikleri görsünüz.

Eğer Node.js sürümünü 14 ile 16 arasında kullanıyorsanız, aşağıdaki komutu kullanınız:

```bash
$ npm run site:devWithNode14-16

Başka bir durumda bu komutu kullanınız:

$ npm run site:dev

Bu, çünkü Node.js 17.X ve sonrası sürümleri belge oluşturma sırasında uyumluluk sorunlarına maruz kalır, bu yüzden OpenSSL'nin eski versiyona indirileceği. Sadece belge oluşturma ve derleme için site:build komutlarını kullanabilirsiniz.

Çıkış Yönetimi

Egg, semver kullanarak sürümleri yönetmektedir.

Ramak Politikası

Ramak master şu anki mevcut stabil sürümü içerirken, ramak next gelecek sürümü geliştirilmekte olan durumu içerir.

• Sadece iki sürüm desteklenir. Güvenlik güncellemeler dışında, tüm düzeltmeler sadece master ve next ramaklarına uygulanır ve diğer güncellemeler son stabil sürümüne yönlendirilir.
• Tüm eski API'lar geçersiz olarak işaretlenmelidir ve yeni sürüm çıkana kadar çalışmaya devam edecektir.
• Ramak master bir sürüm etiketi yoktur, üst seviye semantik sürüm numarasını kullanır.
• Ramak next next etiketini kullanır, üst seviye egg@next ile gelecek sürümü test etmek için kullanabilir.
• Egg, Milestones'da belirlenen sürümlere sürekli olarak destek verir. Her açık sürüm, destek alacaktır.

Çıkış Politikası

Her sürüm, proje yöneticisi (PM) tarafından yönetilir ve aşağıdaki görevleri yerine getirmesi beklenir:

Hazırlık Çalışmaları:

• Sürüm milestone'sunu oluşturun, onunla ilişkili tüm talepleri onaylayın, bilinen sorunları belirtin, örneğin [1.x Milestone].
• Ramak master'dan ramak next'i oluşturun ve next etiketini ayarlayın.

Çıkıştan Önce:

• Bilinen tüm sorunların kapandığını veya ertelenildiğini doğrulayın, performans testlerini tamamlayın.

• Yeni bir [Pull Request]'i oluşturun, [node tarih notları] biçiminde değişiklik tarihini oluşturun, sürümü ilgili belgeyi güncelleştirin, otomatik olarak üretilmiş commit'ler:

  $ npm run commits

• Yeni bir sürüm yöneticisi atayın.

Çıkış Süresi İçinde:

• Eski stabilit denilen sürüm (master) yeni sürüm adıyla (örneğin 1.x) bir ramakta saklanır ve release-{v}.x etiketi (v - mevcut sürüm, örneğin release-1.x) ayarlanır.
• Ramak next'i ramak master'e taşınır, yeni stabilit denilen sürüm olur, next etiketi kaldırılır, README'e göre güncellenir.
• Yeni stabilit denilen sürüm npm üzerinden yayınlanır ve üst seviyeye güncelleme gerektiği bildirilsin.
• npm publish kullanmadan önce, npm paketi yayınladım belgesini okuyun.

Tüm yukarıda bahsedilen etiketler, package.json dosyasındaki npm etiketlerini ayarlamanıza karşılık gelir.

"publishConfig": {
  "tag": "next"
}