Синхронизация с оригиналом (глава 5)

book/05-distributed-git/sections/contributing.asc

@@ -51,38 +51,42 @@ image::images/git-diff-check.png["Вывод команды `git diff --check`"]
 Далее, постарайтесь делать коммит логически разделённого набора изменений.
 Если возможно, попытайтесь делать ваши изменения легко понятными -- не нужно писать код все выходные, работая над пятью разными задачами, а в понедельник отправлять результат как один большой коммит.
 Даже если вы не делали коммиты на выходных, то в понедельник используйте область подготовленных файлов для того, чтобы разделить проделанную работу по принципу минимум один коммит на задачу, давая полезные комментарии к каждому из них.
-Если несколько изменений касаются одного файла, используйте `git add --patch` для частичного добавления файлов в индекс (детально описано в <<ch07-git-tools#r_interactive_staging>>).
+Если несколько изменений касаются одного файла, используйте `git add --patch` для частичного добавления файлов в индекс (детально описано в разделе <<ch07-git-tools#r_interactive_staging>>).
 Состояние проекта в конце ветки не зависит от количества сделанных вами коммитов, так как все изменения добавятся в один момент, поэтому постарайтесь облегчить задачу вашим коллегам, когда они будут просматривать ваши изменения.
+
 Такой подход так же облегчает извлечение или отмену отдельных изменений, если это вдруг потребуется в будущем.
-<<ch07-git-tools#r_rewriting_history>> описывает ряд полезных трюков Git для переписывания истории изменений и интерактивного индексирования -- используйте эти инструменты для создания чистой и понятной истории перед отправкой проделанной работы кому-то ещё.
+Раздел <<ch07-git-tools#r_rewriting_history>> описывает ряд полезных трюков Git для переписывания истории изменений и интерактивного индексирования -- используйте эти инструменты для создания чистой и понятной истории перед отправкой проделанной работы кому-то ещё.
 
 Последнее, что нужно иметь ввиду -- это сообщение коммита.
 Привычка создавать качественные сообщения к коммитам позволяет упростить использование и взаимодействие посредством Git.
 Как правило, ваши сообщения должны начинаться кратким однострочным описанием не более 50 символов, затем должна идти пустая строка, после которой следует более детальное описание.
-Проект Git требует, чтобы детальное описание включало вашу мотивацию при внесении изменения и сравнение с текущей реализацией -- это хороший пример для подражания.
-Так же хорошей идеей будет использование фраз в повелительном наклонении настоящего времени.
-Другими словами -- используйте команды.
-Вместо «Я добавил тесты для» или «Добавление тестов для», используйте «Добавить тесты для».
-Ниже представлен шаблон, написанный Tim Pope:
+Проект Git требует, чтобы детальное описание включало причину внесения изменений и сравнение с текущей реализацией -- это хороший пример для подражания.
+Пишите сообщение коммита в императиве: «Fix bug» а не «Fixed bug» или «Fixes bug».
+Вот отличный шаблон хорошего сообщения коммита, который мы слегка адаптировали из шаблона, https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[изначально написанного Тимом Поупом]:
 
 [source,text]
 ----
-Краткое (50 символов или меньше) описание изменений
+Краткое (не более 50 символов) резюме с заглавной буквы
+
+Более детальный, поясняющий текст, если он требуется.
+Старайтесь не превышать длину строки в 72 символа.
+В некоторых случаях первая строка подразумевается как тема письма, а всё остальное -- как тело письма.
+Пустая строка, отделяющая сводку от тела, имеет решающее значение 
+(за исключением случаев, когда детального описания нет);
+в противном случае такие инструменты, как rebase, могут вас запутать.
 
-Текст более детального описания, если необходим. Старайтесь
-не превышать длину строки в 72 символа. В некоторых случаях
-первая строка подразумевается как тема письма, а всё остальное -- 
-тело письма. Пустая строка, разделяющая сообщение, критически важна
-(если существует детальное описание); такие утилиты как rebase
-могут запутаться, если вы запустите сразу две.
+Сообщения коммитов следует писать используя неопределенную форму глагола совершенного вида повелительного наклонения: «Fix bug» (Исправить баг), а не «Fixed bug» (Исправлен баг) или «Fixes bug» (Исправляет баг).
+Это соглашение соответствует сообщениям коммитов, генерируемых такими командами, как `git merge` и `git revert`.
 
-Последующие параграфы должны отделяться пустыми строками.
+Последующие абзацы идут после пустых строк.
 
-  - Списки тоже подходят
+  - Допускаются обозначения пунктов списка
 
   - Обычно, элементы списка обозначаются с помощью тире или звёздочки,
-    предваряются одиночным пробелом, а разделяются пустой строкой, но
+    с одним пробелом перед ними, а разделяются пустой строкой, но
     соглашения могут отличаться
+
+  - Допускается обратный абзацный отступ.
 ----
 
 Вам и вашим разработчикам будет гораздо проще, если все сообщения ваших коммитов будут так выглядеть.
@@ -97,7 +101,7 @@ image::images/git-diff-check.png["Вывод команды `git diff --check`"]
 ====
 
 [[r_private_team]]
-==== Частная небольшая команда
+==== Небольшая команда
 
 (((contributing, private small team)))
 Самая простая ситуация, с которой вы можете столкнуться, это частный проект с одним или двумя другими разработчиками.
@@ -322,7 +326,7 @@ image::images/small-team-7.png["История коммитов Джессики
 .Общий вид последовательности событий в рабочем процессе для нескольких разработчиков
 image::images/small-team-flow.png["Общий вид последовательности событий в рабочем процессе для нескольких разработчиков"]
 
-==== Частная управляемая команда
+==== Команда с руководителем
 
 (((contributing, private managed team)))
 В этом сценарии мы рассмотрим роли участников в более крупной частной команде.
@@ -520,15 +524,15 @@ $ git commit
 
 [NOTE]
 ====
-Если вы захотите использовать `rebase -i` для схлопывания коммитов в единый или для их перестановки чтобы облегчить модерирование ваших патчей -- воспользуйтесь разделом <<ch07-git-tools#r_rewriting_history>> для получения детальной информации об интерактивном перебазировании.
+Возможно, вы захотите использовать `rebase -i`, чтобы объединить несколько коммитов в один или переставить их местами, чтобы сопровождающему было легче проверять патч -- смотрите раздел <<ch07-git-tools#r_rewriting_history>> для получения детальной информации об интерактивном перебазировании.
 ====
 
 Когда работа в тематической ветке завершена и вы готовы передать изменения исходному проекту, перейдите на страницу исходного проекта и нажмите кнопку «Fork», тем самым создавая доступный для записи форк проекта.
 Затем нужно добавить URL на созданный проект как второй удалённый репозиторий, в нашем случае с именем `myfork`:
 
 [source,console]
 ----
-$ git remote add myfork (url)
+$ git remote add myfork <url>
 ----
 
 После этого следует отправить проделанную работу в него.
@@ -618,8 +622,8 @@ image::images/public-small-2.png["История коммитов после р
 [source,console]
 ----
 $ git checkout -b featureBv2 origin/master
-$ git merge --no-commit --squash featureB
-# (change implementation)
+$ git merge --squash featureB
+  ... change implementation ...
 $ git commit
 $ git push myfork featureBv2
 ----
@@ -641,8 +645,8 @@ image::images/public-small-3.png["История коммитов после р
 Так как существует несколько больших старых проектов, которые принимают патчи посредством почтовых рассылок, мы рассмотрим такой пример.
 
 Рабочий процесс похож на предыдущий -- вы создаёте тематическую ветку для каждого набора патчей, над которыми собираетесь работать.
-Основное отличие -- это способ их передачи проекту.
-Вместо того, чтобы создать форк и отправить в него свои изменения, вы генерируете e-mail версию для каждого набора коммитов и отправляете её в почтовую рассылку разработчиков:
+Основное отличие в способе их передачи проекту.
+Вместо того, чтобы форкнуть проект и отправить в него свои изменения, вы генерируете почтовую версию для каждого набора коммитов с целью отправки её в список рассылки разработчиков:
 
 [source,console]
 ----
@@ -655,7 +659,7 @@ $ git commit
 
 (((git commands, format-patch)))
 Сейчас у вас два коммита, которые вы хотите отправить в почтовую рассылку.
-Используйте команду `git format-patch` для генерации файлов в формате mbox, которые можно отправить по почте -- это обернёт каждый коммит в e-mail сообщение, где первая строка из сообщения коммита будет темой письма, а остальные строки плюс сам патч будут телом письма.
+Используйте команду `git format-patch` для генерации файлов в формате mbox, которые можно отправить по почте -- это обернёт каждый коммит в сообщение e-mail, где первая строка из сообщения коммита будет темой письма, а остальные строки плюс сам патч будут телом письма.
 Применение патча в формате e-mail, сгенерированного с помощью команды `format-patch`, сохраняет всю информацию о коммите должным образом.
 
 [source,console]
@@ -709,7 +713,7 @@ index 76f47bc..f9815f1 100644
 Позже мы покажем как отправлять патчи через Gmail, так сложилось что мы знаем этот почтовый агент лучше других; вы можете воспользоваться инструкциями по использованию большого числа почтовых программ в вышеупомянутом файле `Documentation/SubmittingPatches` из исходных кодов Git.
 
 (((git commands, config)))(((email)))
-Для начала, следует настроить imap секцию в файле `~/.gitconfig`.
+Для начала, следует настроить раздел imap в файле `~/.gitconfig`.
 Каждое отдельное значение можно установить вызовом команды `git config`, а можно указать вручную сразу в файле, но в итоге файл конфигурации должен выглядеть следующим образом:
 
 [source,ini]
@@ -728,7 +732,7 @@ index 76f47bc..f9815f1 100644
 
 [source,console]
 ----
-$ cat *.patch | git imap-send
+$ cat *.patch |git imap-send
 Resolving imap.gmail.com... ok
 Connecting to [74.125.142.109]:993... ok
 Logging in...
@@ -739,7 +743,7 @@ sending 2 messages
 Теперь вы можете перейти в папку Drafts, изменить поле To, указав адрес почтовой рассылки, при необходимости заполнить поле СС, указав адрес сопровождающего или ответственного, и отправить письмо.
 
 Так же вы можете отправить свои патчи используя SMTP сервер.
-Как и в предыдущем случае, вы можете использовать набор команд `git config` или создать секцию sendemail в файле `~/.gitconfig`:
+Как и в предыдущем случае, вы можете использовать набор команд `git config` или создать секцию `sendemail` в файле `~/.gitconfig`:
 
 [source,ini]
 ----
@@ -790,6 +794,11 @@ Result: OK
 
 ==== Заключение
 
-В этом разделе рассмотрен ряд основных рабочих процессов, с которыми вы можете столкнуться при участии в различных Git проектах, а так же представлен ряд новых инструментов, чтобы помочь вам управлять этим процессом.
-Далее, вы взглянете на работу с другой стороны: сопровождение Git проекта.
-Вы научитесь быть доброжелательным диктатором или менеджером по интеграции.
+В этом разделе мы рассмотрели ряд общепринятых схем рабочих процессов и поговорили о различиях между работой в составе небольшой команды над проектами с закрытым исходным кодом и участием в большом публичном проекте.
+Вы знаете, что нужно проверять ошибки в пробелах перед созданием коммита и можете написать отличное сообщение коммита.
+Вы научились оформлять патчи и отправлять их по электронной почте в список рассылки разработчиков.
+Работа со слияниями также была покрыта в контексте различных рабочих процессов.
+Теперь вы хорошо подготовлены для совместной работы над любым проектом.
+
+Далее рассмотрим ситуацию с другой стороны: как сопровождать проект Git.
+Вы узнаете, как быть великодушным диктатором или менеджером по интеграции.