Правила для внесения вклада

Перед отправкой проблемы

• Если вы не используете последнюю версию master для генерации клиентских приложений API или серверных шаблонов, пожалуйста, попробуйте еще раз, обновив до последней версии master, так как проблема может быть уже решена. Ссылка: Начало работы
• Поищите открытые проблемы и закрытые проблемы, чтобы убедиться, что никто другой не сообщил о чем-то подобном ранее.
• Отправьте тикет проблемы, предоставив всю необходимую информацию.
• Тестирование с последней версией master можно выполнить, собрав JAR локально, чтобы проверить, была ли проблема уже решена.
• Вы также можете сделать предложение или задать вопрос, открыто создав "проблему".

Перед отправкой pull request

• Поищите открытые проблемы, чтобы убедиться, что никто другой не сообщил о чем-то подобном и никто не работает над аналогичным предложенным изменением.
• Если никто не сделал подобное предложение, откройте "проблему" со своим предложением, чтобы собрать отзывы сообщества.
• Рекомендуется создать новый git-ветвь для изменения, чтобы сообщение слияния выглядело более приятно в истории коммитов.## Как вносить вклад

Git

Если вы новичок в git, вы можете найти полезными следующие часто задаваемые вопросы:

https://github.com/swagger-api/swagger-codegen/wiki/FAQ#git

Генераторы кода

Все генераторы кода можно найти в modules/swagger-codegen/src/main/java/io/swagger/codegen/languages

Шаблоны

Все шаблоны (mustache) можно найти в modules/swagger-codegen/src/main/resources.Для списка доступных переменных в шаблоне обратитесь к этой странице

Правила оформления кода

Изменения в коде должны соответствовать стилю оформления кода для соответствующих языков программирования:

• Ada: https://en.wikibooks.org/wiki/Ada_Style_Guide/Source_Code_Presentation
• Android: https://source.android.com/source/code-style.html
• Bash: https://github.com/bahamas10/bash-style-guide
• C#: https://msdn.microsoft.com/en-us/library/vstudio/ff926074.aspx
• C++: https://google.github.io/styleguide/cppguide.html
• C++ (Tizen): https://wiki.tizen.org/Native_Platform_Coding_Idiom_and_Style_Guide#C.2B.2B_Coding_Style
• Clojure: https://github.com/bbatsov/clojure-style-guide
• Dart: https://www.dartlang.org/guides/language/effective-dart/style
• Elixir: https://github.com/christopheradams/elixir_style_guide
• Eiffel: https://www.eiffel.org/doc/eiffel/Coding%20Standards
• Erlang: https://github.com/inaka/erlang_guidelines
• Haskell: https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
• Java: https://google.github.io/styleguide/javaguide.html
• JavaScript: https://github.com/airbnb/javascript/
• Kotlin: https://kotlinlang.org/docs/reference/coding-conventions.html
• Groovy: http://groovy-lang.org/style-guide.html
• Go: https://github.com/golang/go/wiki/CodeReviewComments
• ObjC: https://github.com/NYTimes/objective-c-style-guide
• Perl: http://perldoc.perl.org/perlstyle.html
• PHP: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md
• PowerShell: https://msdn.microsoft.com/en-us/library/dd878270(v=vs.85).aspx
• Python: https://www.python.org/dev/peps/pep-0008/
• R: https://google.github.io/styleguide/Rguide.xml
• Ruby: https://github.com/bbatsov/ruby-style-guide
• Rust: https://github.com/rust-lang-nursery/fmt-rfcs/blob/master/guide/guide.md (the default rustfmt configuration)
• Scala: http://docs.scala-lang.org/style/
• Swift: Apple Developer
• TypeScript: https://github.com/microsoft/TypeScript/wiki/Coding-Conventions# Кодирование-руководства

Для других языков вы можете предложить свои варианты.

(com/Microsoft/TypeScript/wiki/Coding-guidelines)Вы можете найти, что текущий базовый код не полностью соответствует стилю программирования, и мы приветствуем вклады для исправления этих недочетов.

Для расширений поставщика, пожалуйста, следуйте названию ниже:

• Для общих расширений поставщика используйте строчные буквы и дефис. Например, x-is-unique, x-content-type
• Для языковых специфических расширений поставщика, используйте формат x-{lang}-{extension-name}. Например, x-objc-operation-id, x-java-feign-retry-limit
• Для списка существующих расширений поставщика, используемых в настоящий момент, обратитесь к https://github.com/swagger-api/swagger-codegen/wiki/Vendor-Extensions. Если вы добавили новые расширения поставщика как часть вашего запроса на внесение изменений (PR), пожалуйста, обновите страницу вики.

Тестирование

Чтобы добавить тестовые случаи (необязательно) для охвата изменений в генераторе кода, обратитесь к модули/swagger-codegen/src/test/java/io/swagger/codegenЧтобы протестировать шаблоны, выполните следующие действия:

• Обновите образец Petstore запустив скрипт командной строки из папки bin. Например, запустите ./bin/ruby-petstore.sh для обновления Ruby PetStore API клиента в папке samples/client/petstore/ruby. Для Windows, скрипты батника можно найти в папке bin\windows. (Если вы заметили, что были созданы новые файлы или произошли неожиданные изменения в результате обновления, это не является необычным, так как тестовые случаи добавляются в OpenAPI/Swagger спецификацию время от времени. Если у вас есть вопросы или опасения, пожалуйста, откройте тикет для начала обсуждения)
• Выполните тесты в папке с образцами, например, в samples/client/petstore/ruby, запустите mvn integration-test -rf :RubyPetstoreClientTests. (некоторые языки могут не содержать юнит-тестирования для Petstore, и мы ищем вклады от сообщества для реализации этих тестов)
• Наконец, выполните git commit -a для коммита обновленных образцов файлов: (git add -A если добавлены новые файлы с тестовыми случаями)Чтобы запустить CI тесты, вы можете выполнить mvn verify -Psamples (предполагая, что у вас установлены все необходимые инструменты для выполнения тестов для различных языков) или вы можете использовать http://travis-ci.org для запуска CI тестов, добавив свой собственный репозиторий Swagger-Codegen.

Советы

• Меньшие изменения легче проверять
• [Необязательно] Для исправления ошибок предоставьте OpenAPI Spec для воспроизведения проблемы, чтобы рецензент мог использовать её для подтверждения исправления
• Добавьте тестовый случай(и) для охвата изменения
• Документируйте исправление в коде, чтобы сделать его более читаемым
• Убедитесь, что тестовые случаи прошли после изменения (одним из способов является использование https://travis-ci.org/ для запуска CI тестов)
• Отправьте PR с осмысленным заголовком, описанием и сообщением о коммите. Пример хорошего PR: PR-3306
• Рекомендованные настройки git
  • git config --global core.autocrlf input для того, чтобы указать Git конвертировать CRLF в LF при коммите, но не наоборот
• Чтобы автоматически закрыть задачу (например, задача 1542) после слияния PR, используйте ключевые слова "fix", "close", "resolve" в описании PR, например fix #1542. (См.: закрытие задач с помощью ключевых слов)