Вносим вклад в Ruby on Rails

Это руководство раскрывает способы, с помощью которых ты можешь стать частью продолжающейся разработки Ruby on Rails.

После прочтения этого руководства, вы узнаете:

  • Как использовать GitHub для сообщения о проблемах.
  • Как клонировать master и запустить тестовый набор.
  • Как помочь в решении существующих проблем.
  • Как внести вклад в документацию Ruby on Rails.
  • Как внести вклад в код Ruby on Rails.

Ruby on Rails — это не "чей-то там фреймворк". На протяжение лет сотни людей вносили вклад в Ruby on Rails, от одиночного символа до огромных архитектурных изменений или значимой документации — и все это с целью сделать Ruby on Rails лучше для каждого. Даже если вы пока не готовы писать код или документацию, имеется ряд других способов, которыми вы можете внести вклад, от сообщений о проблемах до тестирования новых изменений.

Как упомянуто в Rails README, от каждого, участвующего в коде Rails и его подпроектах, системах отслеживания ошибок, чатах и списках рассылок, ожидается следование нормам поведения Rails.


1. Сообщение о проблеме

Ruby on Rails использует GitHub Issue Tracking для отслеживания проблем (в основном, багов и нового кода). Если вы нашли баг в Ruby on Rails, нужно начать отсюда. Чтобы сообщить о проблеме, прокомментировать ее или создавать пул-реквесты, необходимо создать аккаунт (бесплатный) на GitHub.

Багам в самой последней версии Ruby on Rails уделяется наибольшее внимание. Также, основная команда Rails всегда заинтересована в обратной связи от тех, у кого есть время потестировать edge Rails (код версии Rails, которая разрабатывается в текущий момент). Позже в этом руководстве будет рассказано, как получить edge Rails для тестирования.

1.1. Создание отчета о баге

Если вы обнаружили проблему в Ruby on Rails, не несущую риск безопасности, произведите поиск по Issues, о ней уже может быть сообщено. Если вы не обнаружили какую-либо открытую проблему на GitHub, посвященную ошибке, которую вы нашли, вашим следующим действием будет открыть новую проблему. (О сообщениях о проблемах безопасности смотрите следующий раздел.)

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

А затем, не теряйте надежды! Если у вас некритичный баг, вы создаете этот отчет о проблеме в надежде, что другие с той же проблемой смогут взаимодействовать с вами, чтобы ее решить. Не ожидайте, что этот отчет о проблеме автоматически увидит какую-либо активность, или что другие переключатся на нее, чтобы починить. Создание отчета о подобной проблеме является больше помощью самому себе на пути к починке проблемы и другим для подтверждения ее с помощью комментария "I'm having this problem too".

1.2. Создание исполняемого тестового случая

Наличие способа воспроизвести вашу проблему будет очень полезным для других, чтобы подтвердить, исследовать и, в конечном счете, починить вашу проблему. Это можно сделать с помощью исполняемого тестового случая. Чтобы упростить этот процесс, мы подготовили для вас несколько шаблонов отчетов об ошибке, которые можно использовать в качестве отправной точки:

  • Шаблон для проблем с Active Record (модели, база данных): gem / master
  • Шаблон для тестирования проблем с Active Record (миграции): gem / master
  • Шаблон для проблем с Action Pack (контроллеры, роутинг): gem / master
  • Шаблон для проблем с Active Job: gem / master
  • Шаблон для других проблем: gem / master

Эти шаблоны включают шаблонный код для настройки тестового случая для либо выпущенной версии Rails (*_gem.rb), либо разрабатываемого Rails (*_master.rb).

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

1.3. Особая трактовка проблем безопасности

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

1.4. Что насчет запросов о новой фиче?

Пожалуйста не складывайте "feature request" в GitHub Issues. Если имеется новая фича, которую вы бы хотели видеть добавленной в Ruby on Rails, вам необходимо написать код самим, или убедить кого-то другого помочь вам с написанием кода. Позже в этом руководстве будут даны подробные инструкции по предложению изменений в Ruby on Rails. Если вы опубликуете список пожеланий в GitHub Issues без кода, будьте уверены, он будет помечен "invalid", как только будет рассмотрен.

Иногда грань между 'баг' и 'фича' трудно провести. Как правило, фича — это все, что добавляет новое поведение, в то время как баг — это все, что вызывает неправильное поведение. Иногда основная команда будет делать личное суждение. Это означает, как правило, что различие лишь влияет на то, в какой релиз пойдет ваше изменение; они любят представление фич! Они всего лишь не портируют их в поддерживаемые ветки.

Если вы хотите получить обратную связь на идею фичи до того, как начнете работать над изменениями, напишите письмо в список рассылки rails-core. Вы можете не получить откликов, что означает, что всем безразлично. Вы можете найти кого-то, кто также заинтересован в создании этой фичи. Вы можете получить "This won't be accepted." Но это подходящее место для обсуждения новых идей. GitHub Issues являются не особо хорошим местом для проведения длительных и обширных обсуждений новых фич.

2. Помощь в разрешении существующих проблем

В качестве следующего шага после сообщения о проблемах, вы можете помочь основной команде разрешить существующие проблемы. Если вы посмотрите на список проблем в GitHub Issues, вы обнаружите множество проблем, требующих сейчас внимания. Что вы можете с ними сделать? Фактически, немного:

2.1. Подтвердить сообщение о баге

Начинающие могут помочь только в подтверждении сообщений о багах. Сможете ли вы воспроизвести сообщенную проблему на своем компьютере? Если так, можете добавить комментарий к проблеме, что вы наблюдали то же самое.

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

Если вы обнаружили сообщение о баге без теста, было бы полезным внести вклад, написав падающий тест. Это также отличный способ исследования исходного кода: глядя на существующие файлы тестов, вы научитесь, как писать больше тестов. Новые тесты лучше всего вносить в виде изменений, как объяснено позже в разделе "Вносим вклад в код Rails".

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

2.2. Протестировать изменения

Также можно помочь, изучая пул-реквесты, которые были отправлены в Ruby on Rails с помощью GitHub. Для применения чьих-то изменений, вам сначала необходимо создать отдельную ветку:

$ git checkout -b testing_branch

Затем вы можете использовать их удаленную ветку для обновления кода в своей. Например, скажем, что на GitHub пользователь JohnSmith форкнул и запушил в ветку "orange", расположенную в https://github.com/JohnSmith/rails.

$ git remote add JohnSmith https://github.com/JohnSmith/rails.git
$ git pull JohnSmith orange

После применения его ветки, протестируйте ее! Вот несколько вещей, о которых стоит подумать:

  • Работает ли фактически это изменение?
  • Довольны ли вы тестами? Сможете ли вы выполнить то, что они тестируют? Нет ли отсутствующих тестов?
  • Имеется ли достаточное покрытие документацией? Должна ли быть обновлена документация где-то еще?
  • Нравится ли вам реализация? Можете подумать о более красивом или быстром способе реализации части его изменений?

Как только вы будете довольны тем, что пул-реквест содержит хорошее изменение, прокомментируйте на GitHub, что вы одобряете. Ваш комментарий должен показать, что вам нравится изменение, и что вы думаете о нем. Что-то вроде:

I like the way you've restructured that code in generate_finder_sql - much nicer. The tests look good too.

Если ваш комментарий просто содержит "+1", есть шанс, что прочие ревьюверы не воспримут его серьезно. Покажите, что вы потратили время на обзор этого пул-реквеста.

3. Вносим вклад в документацию Rails

В Ruby on Rails имеется два главных набора документации: руководства, помогающие изучить Ruby on Rails, и API, также служащее в качестве эталона.

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

Вы можете либо открыть пул-реквест в Rails или попросить основную команду Rails открыть доступ к docrails, если вы вносите вклад регулярно. Пожалуйста, не открывайте пул-реквесты в docrails, если хотите получить обратную связь на свои изменения, попросите ее лучше в Rails.

Docrails регулярно сливается с master, таким образом вы можете эффективно редактировать документацию Ruby on Rails.

Если вы не уверены в изменениях документации, можете создать проблему в трекере Rails на GitHub.

При работе с документацией принимайте во внимание рекомендации по документированию API и рекомендации для руководств по Ruby on Rails.

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

Чтобы помочь нашим серверам CI, следует добавлять [ci skip] в сообщения вашего коммита в документацию, чтобы они игнорировали этот коммит. Пожалуйста, используйте его для коммитов, содержащих только изменения документации.

В docrails имеется очень строгая политика: не должен быть затронут какой-либо код, неважно, насколько тривиально или мало изменение. С помощью docrails может быть отредактированы только RDoc и руководства. А также, CHANGELOG никогда не должны правиться в docrails.

4. Перевод руководств Rails

Мы счастливы, что находятся волонтеры, переводящие руководства Rails на их языки. Если вы хотите перевести руководства Rails на ваш язык, следуйте этим шагам:

  • Сделайте форк проекта (rails/rails).
  • Добавьте папку исходников для вашего языка, например: guides/source/it-IT для итальянского.
  • Скопируйте содержимое guides/source в директорию для вашего языка и переведите их.
  • НЕ переводите файлы HTML, так как они генерируются автоматически.

Чтобы сгенерировать руководства в формате HTML, войдите в директорию guides и запустите (например, для it-IT):

$ bundle install
$ bundle exec rake guides:generate:html GUIDES_LANGUAGE=it-IT

Это сгенерирует руководства в директории output.

Эти инструкции для Rails > 4. Гем Redcarpet не работает с JRuby.

Деятельность по переводу, о которой мы знаем (разные версии):

5. Вносим вклад в код Rails

5.1. Настраиваем среду разработки

Чтобы продвинуться от подтверждения багов к помощи в разрешении существующих проблем или внесения собственного кода в Ruby on Rails, вы должны уметь запускать его тестовый набор. В этом разделе руководства вы изучите, как настроить тесты на своем компьютере.

5.1.1. Простой способ

Простейшим и рекомендованным способом получить среду разработки, готовую для программирования, является использование Rails development box.

5.1.2. Сложный способ

В случае, если вы не можете использовать Rails development box, смотрите другое руководство.

5.2. Клонирование репозитория Rails

Чтобы вносить изменения в код, необходимо клонировать репозиторий Rails:

$ git clone https://github.com/rails/rails.git

и создать отдельную ветку:

$ cd rails
$ git checkout -b my_new_branch

Не имеет значения, какое имя вы используете, так как эта ветка существует только на вашем локальном компьютере и вашем персональном репозитории на GitHub. Она не будет частью гит-репозитория Rails.

5.3. Bundle install

Установите требуемые гемы.

$ bundle install

5.4. Запуск приложения на вашей локальной ветке

Если вам нужно приложение Rails для тестирования изменений, флажок --dev для rails new создаст приложение, использующее вашу локальную ветку:

$ cd rails
$ bundle exec rails new ~/my-test-app --dev

Приложение, созданное в ~/my-test-app запускается на вашей локальной ветке, и, в частности, видит любые изменения после перезагрузки сервера.

5.5. Пишите свой код

Пора заняться делом и добавить/отредактировать код. Раз вы в своей ветке, вы можете писать все, что хотите (убедитесь, что вы в правильной ветке с помощью git branch -a). Но если вы планируете отправить ваше изменение для включения в Rails, имейте в виду несколько вещей:

  • Пишите правильный код.
  • Используйте идиомы и хелперы Rails.
  • Включайте тесты, которые падают без вашего кода, и проходят с ним.
  • Обновляйте документацию, примеры и руководства: все, что было затронуто вашим вкладом.

Изменения, которые по природе косметические, и не добавляют ничего ощутимого в стаблильность, функциональность или тестируемость Rails, обычно не принимаются (читайте подробнее об обоснованиях этого решения).

5.5.1. Следуйте соглашениям по программированию

Rails следует простому набору соглашений о стиле кода:

  • Два пробела, нет табуляции (для отступов).
  • Нет конечных пробелов. Пустые строчки не должны иметь пробелов.
  • Отступ после private/protected.
  • Используйте синтаксис Ruby >= 1.9 для хэшей. Предпочитайте { a: :b } над { :a => :b }.
  • Предпочитайте &&/|| над and/or.
  • Предпочитайте class << self над self.method для методов класса.
  • Используйте my_method(my_arg), а не my_method( my_arg ) или my_method my_arg.
  • Используйте a = b, а не a=b.
  • Используйте методы assert_not вместо отрицаний.
  • Предпочитайте method { do_stuff } вместо method{do_stuff} для однострочных блоков.
  • Следуйте соглашениям в исходном коде, которые вы уже видели.

Вышеприведенное является руководящими указаниями — используйте собственные суждения при их использовании.

5.6. Тестируйте производительность своего кода

Для изменений, способных повлиять на производительность, пожалуйста, тестируйте производительность вашего кода и измеряйте влияние. Пожалуйста, покажите используемый. Следует рассмотреть включение этой информации в сообщении вашего коммита, позволяющее будущим контрибьюторам с легкостью проверить ваши выводы и определить, являются ли они по прежнему уместными. (Например, будущие оптимизации в виртуальной машине Ruby могут привести к ненужности определенных оптимизаций.)

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

В качестве отправной точки можно использовать шаблон теста производительности. Он включает шаблонный код для настройки теста с помощью гема benchmark-ips. Шаблон разработан для тестирования относительно самодостаточных изменений, которые можно встроить в скрипт.

5.7. Запуск тестов

В Rails не является необходимым запускать полный тестовый набор перед отправкой изменений. В частности, тестовый набор railties занимает много времени, и особенно долго, если исходный код монтирован в /vagrant, как происходит в рекомендованном рабочем процессе с помощью rails-dev-box.

В качестве компромисса, тестируйте то, на что ваш код явно влияет, и, если изменение не в railties, запускайте полный тестовый набор затронутого компонента. Если все тесты проходят, этого достаточно, чтобы предложить ваш вклад. У нас есть Travis CI в качестве безопасной сети для отлова неожиданных поломок где-то еще.

5.7.1. Весь Rails:

Чтобы запустить все тесты, выполните:

$ cd rails
$ bundle exec rake test

5.7.2. Для определенного компонента

Можно запустить тесты только для определенного компонента (такого как Action Pack). Например, чтобы запустить тесты Action Mailer:

$ cd actionmailer
$ bundle exec rake test

5.7.3. Запуск отдельного теста

С помощью ruby можно запустить отдельный тест. К примеру:

$ cd actionmailer
$ bundle exec ruby -w -Itest test/mail_layout_test.rb -n test_explicit_class_layout

Опция -n позволяет запустить отдельный метод вместо всего файла.

5.7.4. Тестирование Active Record

Сначала создайте необходимые вам базы данных. Список необходимых имен таблиц, имен пользователей и паролей можно находится в activerecord/test/config.example.yml.

Для MySQL и PostgreSQL необходим запуск выражений SQL create database activerecord_unittest и create database activerecord_unittest2. Для SQLite3 это необязательно.

Вот как можно запустить тестовый набор Active Record только для SQLite3:

$ cd activerecord
$ bundle exec rake test:sqlite3

Теперь вы можете запускать тесты, как вы делали для sqlite3. Соответствующие задачи:

test:mysql2
test:postgresql

Наконец,

$ bundle exec rake test

запустит все три по очереди.

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

$ ARCONN=sqlite3 bundle exec ruby -Itest test/cases/associations/has_many_associations_test.rb

Чтобы запустить одиночный тест на всех адаптерах, используйте:

$ bundle exec rake TEST=test/cases/associations/has_many_associations_test.rb

Также можно вызвать test_jdbcmysql, test_jdbcsqlite3 или test_jdbcpostgresql. Информацию по запуску нацеленных на базу данных тестов смотрите в файле activerecord/RUNNING_UNIT_TESTS.rdoc, а по запуску тестового набора на сервере CI в файле ci/travis.rb.

5.8. Предупреждения

Тестовый набор запускается с включенными предупреждениями. В идеале, Ruby on Rails не должен выдавать предупреждения, но их может быть несколько, в том числе от сторонних библиотек. Пожалуйста, игнорируйте (или почините!) их, если имеются, и отправляйте изменения, не имеющих новых предупреждений.

Если вы знаете, что делаете, и хотите получить более чистый вывод, есть возможность переопределить флажок:

$ RUBYOPT=-W0 bundle exec rake test

5.9. Обновление CHANGELOG

CHANGELOG — это важная часть каждого релиза. Он содержит список изменений для каждой версии Rails.

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

Запись в CHANGELOG должна кратко описывать то, что было изменено, и заканчиваться именем автора. Можно использовать несколько строчек, если необходимо место, а также можно прикрепить примеры кода с отступом в 4 пробела. Если изменение относится к определенной проблеме, следует прикрепить номер проблемы. Вот пример записи в CHANGELOG:

*   Summary of a change that briefly describes what was changed. You can use multiple
    lines and wrap them at around 80 characters. Code examples are ok, too, if needed:

        class Foo
          def bar
            puts 'baz'
          end
        end

    You can continue after the code example and you can attach issue number. GH#1234

    *Your Name*

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

5.10. Обновление Gemfile.lock

Некоторые изменения требуют обновления зависимостей. В таких случаях убедитесь, что вы запустили bundle update, чтобы получить правильную версию зависимости и сделайте коммит с файлом Gemfile.lock со своими изменениями.

5.11. Проверка разумности

Вы не должны быть единственным, кто смотрит на код до того, как отправить его. Если вы знаете кого-то еще, использующего Rails, попробуйте попросить их посмотреть на вашу работу. Если вы не знаете кого-то, использующего Rails, попробуйте войти в комнату IRC или опубликовать свою идею в рассылке rails-core. Сделав это приватно до того, как вы отправите изменения публично, является "smoke test" для патча: если вы не сможете убедить другого разработчика в красоте своего кода, вы вряд ли убедите в этом члена основной команды.

5.12. Коммит ваших изменений

Когда вы довольны своим кодом на своем компьютере, необходимо закоммитить изменения в Git:

$ git commit -a

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

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

Хорошее сообщение коммита должно выглядеть так:

Краткое содержание (в идеале до 50 символов)

Более детальное описание, если необходимо. Оно должно переноситься по
72 символа. Попытайтесь быть как можно более наглядным. Даже если вы
думаете, что содержание комита очевидно, оно может быть неочевидным для
остальных. Добавьте любое описание, уже присутствующее в
соответствующих описаниях проблем; должно быть необязательным посещение
веб-страницы чтобы посмотреть историю.

Раздел описания может иметь несколько параграфов.

Можно встраивать примеры кода, отступив их на 4 пробелами:

    class ArticlesController
      def index
        render json: Article.limit(10)
      end
    end

Можно добавить маркированные списки:

- создав пункт списка, начав строчку с черточки (-) или звездочки (*)

- перенося динные строки по 72 символа и отступая дополнительные строки
  на 2 символа для читаемости

Пожалуйста, склеивайте свои коммиты в один коммит, когда это уместно. Это упрощает будущие черри-пики и поддерживает чистоту лога.

5.13. Обновление вашей ветки

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

$ git checkout master
$ git pull --rebase

Теперь можно применить ваш патч на последних изменениях:

$ git checkout my_new_branch
$ git rebase master

Нет конфликтов? Тесты все еще проходят? Изменения еще актуальны? Продолжайте.

5.14. Форк

Перейдите в репозиторий Rails на GitHub и нажмите "Fork" в верхнем правом углу.

Добавьте новый удаленный репозиторий к вашему локальному:

$ git remote add mine https://github.com:<your user name>/rails.git

Отправляйте в свой удаленный репозиторий:

$ git push mine my_new_branch

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

В директории, в которую вы клонировали свой форк:

$ git remote add rails https://github.com/rails/rails.git

Скачать новые коммиты и ветки из официального репозитория:

$ git fetch rails

Смержить новое содержимое:

$ git checkout master
$ git rebase rails/master

Обновить ваш форк:

$ git push origin master

Если хотите обновить другую ветку:

$ git checkout branch_name
$ git rebase rails/branch_name
$ git push origin branch_name

5.15. Создание пул-реквеста

Перейдите в репозиторий Rails, в который вы только что отправили код (т.е. https://github.com/your-user-name/rails) и нажмите на "Pull Requests" в правой панели. На следующей странице нажмите "New pull request" в верхнем правом углу.

Нажмите на "Edit", если необходимо изменить сравниваемые ветки (по умолчанию он сравнивает "master") и нажмите "Click to create a pull request for this comparison".

Убедитесь, что включены изменения, которые вы представили. Заполните некоторыми подробностями о вашем потенциальном патче, включая осмысленный заголовок. Когда закончите, нажмите "Send pull request". Основная команда Rails будет уведомлена о вашем изменении.

5.16. Получение обратной связи

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

У некоторых контрибьюторов в Rails включены уведомления по email с GitHub, у некоторых нет. Более того, (почти) все, кто работает над Rails, являются добровольцами, поэтому может пройти несколько дней до того, как вы получите первую обратную связь на пул-реквест. Не отчаивайтесь! Иногда это быстро, иногда это медленно. Такова жизнь открытого ПО.

Если прошло больше недели, и вам никто не ответил, можете попытаться немного ускорить процесс. Для этого используйте рассылку rubyonrails-core. Также можно оставить комментарий в своем пул-реквесте.

ПОка вы ждете обратную связь на свой пул-реквест, откройте несколько чужих пул-реквестов и дайте обратную связь кому-то еще! Мы уверены, они будут признательны за это не меньше, чем вы были бы признательны за обратную связь на ваши изменения.

5.17. Повторение по необходимости

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

5.17.1. Сквош коммитов

Одной из вещей, которая может быть попрошена, является "squash your commits", которая объединит все ваши коммиты в один. Мы предпочитаем пул-реквесты с одним коммитом. Это упрощает обратное портирование в стабильные ветки, откат плохих коммитов, слежение за историей git. Rails — это большой проект, и ряд множество посторонних коммитов может добавить много шума.

Чтобы сделать это, необходимо иметь git remote, указывающий на главный репозиторий Rails. Это в любом случае полезно, но если у вас он не настроен, сначала сделайте:

$ git remote add upstream https://github.com/rails/rails.git

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

Предположим, что ваша ветка называется my_pull_request, тогда нужно сделать следующее:

$ git fetch upstream
$ git checkout my_pull_request
$ git rebase -i upstream/master

< Выберите 'squash' для всех ваших коммитов, кроме первого. >
< Отредактируйте сообщение коммита, чтобы оно было осмысленным, и опишите все свои изменения. >

$ git push origin my_pull_request -f

Далее вам необходимо обновить пул-реквест на GitHub и посмотреть, что он был изменен.

5.17.2. Обновление пул-реквеста

Иногда вас попросят внести некоторые изменения в код, который уже был закоммичен. Это может включать исправление существующих коммитов. В этом случае Git не позволит отправить изменения, так как удаленная и локальная ветки не соответствуют друг другу. Вместо открытия нового пул-реквеста, можно принудить отправку в вашу ветку на GitHub, как описано ранее в разделе про сквош коммитов:

$ git push origin my_pull_request -f

Это позволит обновить ветку и пул-реквест на GitHub вашим новым кодом. Отметьте, что использование принудительной отправки может привести к потере коммитов на удаленной ветке; используйте ее осторожно.

5.18. Старшие версии Ruby on Rails

Если вы хотите добавить исправление в старшие версии Ruby on Rails, необходимо настроить и переключить свою локальную отслеживаемую ветку. Вот пример, как переключиться на ветку 4-0-stable:

$ git branch --track 4-0-stable origin/4-0-stable
$ git checkout 4-0-stable

Возможно, вы захотите выводить имя ветки Git в строке ввода консоли чтобы было проще вспомнить, над какой версией кода вы работаете.

5.18.1. Обратное портирование

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

Для простых изменений, легчайшим способом портировать ваши изменения является извлечь diff ваших изменений в master и применить его в целевой ветке.

Сначала убедитесь, что только ваши изменения составляют разницу между вашей текущей веткой и master:

$ git log master..HEAD

Затем извлеките diff:

$ git format-patch master --stdout > ~/my_changes.patch

Переключитесь в целевую ветку и примените ваши изменения:

$ git checkout -b my_backport_branch 4-2-stable
$ git apply ~/my_changes.patch

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

Как только вы разрешили все конфликты и убедились, что проходят все тесты, отправьте свои изменения и откройте отдельный пул-реквест для своего порта. Также важно отметить, что старшие ветки могут иметь другой список целевых версий, чем в master. По возможности, лучше до от отправки пул-реквеста протестировать порт локально на версиях Ruby, перечисленных в .travis.yml.

А затем... подумайте о следующем вкладе!

6. Авторы Rails

Все внесшие вклад или в master, или в docrails, восхваляются в Rails Contributors.