diff --git a/doc/dev_guide/developer_guidelines.rst b/doc/dev_guide/developer_guidelines.rst index 344c87ffea..3f5e0dc5c8 100644 --- a/doc/dev_guide/developer_guidelines.rst +++ b/doc/dev_guide/developer_guidelines.rst @@ -109,206 +109,3 @@ Some real-world examples: Based on [`1 `_] and [`2 `_]. - -.. _dev_guidelines-patch-review: - -=========================================================== -How to submit a patch for review -=========================================================== - -We don't accept GitHub pull requests. Instead, all patches -should be sent as plain-text messages to tarantool-patches@dev.tarantool.org. -Please subscribe to our mailing list -at https://lists.tarantool.org/mailman/listinfo/tarantool-patches -to ensure that your messages are added to the archive. - -1. **Preparing a patch** - -Once you have committed a patch to your local git repository, you can -submit it for review. - -To prepare an email, use ``git format-patch`` command: - -.. code-block:: console - - $ git format-patch -1 - -It will format the commit at the top of your local git repository as -a plain-text email and write it to a file in the current directory. -The file name will look like ``0001-your-commit-subject-line.patch``. -To specify a different directory, use ``-o`` option: - -.. code-block:: console - - $ git format-patch -1 -o ~/patches-to-send - -Once the patch has been formatted, you can view and edit it with your -favorite text editor (after all, it is a plain-text file!). We strongly -recommend adding: - -* a hyperlink to the branch where this patch can be found at GitHub, and -* a hyperlink to the GitHub issue your patch is supposed to fix, if any. - -If there is just one patch, the change log should go right after ``---`` in the -message body (it will be ignored by ``git am`` then). - -If there are multiple patches you want to submit in one go (e.g. this is -a big feature which requires some preparatory patches to be committed -first), you should send each patch in a separate email in reply to a cover -letter. To format a patch series accordingly, pass the following options -to ``git format-patch``: - -.. code-block:: console - - $ git format-patch --cover-letter --thread=shallow HEAD~2 - -where: - -* ``--cover-letter`` will make ``git format-patch`` generate a cover letter; -* ``--thread=shallow`` will mark each formatted patch email to be sent - in reply to the cover letter; -* ``HEAD~2`` (we now use it instead of ``-1``) will make ``git format-patch`` - format the first two patches at the top of your local git branch instead - of just one. To format three patches, use ``HEAD~3``, and so forth. - -After the command has been successfully executed, you will find all your -patches formatted as separate emails in your current directory (or in the -directory specified via ``-o`` option): - -.. code-block:: none - - 0000-cover-letter.patch - 0001-first-commit.patch - 0002-second-commit.patch - ... - -The cover letter will have BLURB in its subject and body. You'll have to -edit it before submitting (again, it is a plain text file). Please write: - -* a short series description in the subject line; -* a few words about each patch of the series in the body. - -And don't forget to add hyperlinks to the GitHub issue and branch where -your series can be found. In this case you don't need to put links or any -additional information to each individual email -- the cover letter will -cover everything. - -.. NOTE:: - - To omit ``--cover-letter`` and ``--thread=shallow`` options, you can - add the following lines to your gitconfig: - - .. code-block:: none - - [format] - thread = shallow - coverLetter = auto - -2. **Sending a patch** - -Once you have formatted your patches, they are ready to be sent via email. -Of course, you can send them with your favorite mail agent, but it is -much easier to use ``git send-email`` for this. Before using this command, -you need to configure it. - -If you use a GMail account, add the following code to your ``.gitconfig``: - -.. code-block:: none - - [sendemail] - smtpencryption = tls - smtpserver = smtp.gmail.com - smtpserverport = 587 - smtpuser = your.name@gmail.com - smtppass = topsecret - -For mail.ru users, the configuration will be slightly different: - -.. code-block:: none - - [sendemail] - smtpencryption = ssl - smtpserver = smtp.mail.ru - smtpserverport = 465 - smtpuser = your.name@mail.ru - smtppass = topsecret - -If your email account is hosted by another service, consult your service -provider about your SMTP settings. - -Once configured, use the following command to send your patches: - -.. code-block:: console - - $ git send-email --to tarantool-patches@dev.tarantool.org 00* - -(``00*`` wildcard will be expanded by your shell to the list of patches -generated at the previous step.) - -If you want someone in particular to review your patch, add them to the -list of recipients by passing ``--to`` or ``--cc`` once per each recipient. - -.. NOTE:: - - It is useful to check that ``git send-email`` will work as expected - without sending anything to the world. Use ``--dry-run`` option for that. - -3. **Review process** - -After having sent your patches, you just wait for a review. The reviewer -will send their comments back to you in reply to the email that contains -the patch that in their opinion needs to be fixed. - -Upon receiving an email with review remarks, you carefully read it and reply -about whether you agree or disagree with. Please note that we use the -interleaved reply style (aka "inline reply") for communications over email. - -Upon reaching an agreement, you send a fixed patch in reply to the email that -ended the discussion. To send a patch, you can either attach a plain diff -(created by ``git diff`` or ``git format-patch``) to email and send it with your -favorite mail agent, or use ``--in-reply-to`` option of ``git send-email`` -command. - -If you feel that the accumulated change set is large enough to send the -whole series anew and restart the review process in a different thread, -you generate the patch email(s) again with ``git format-patch``, this time -adding v2 (then v3, v4, and so forth) to the subject and a change log to -the message body. To modify the subject line accordingly, use the -``--subject-prefix`` option to ``git format-patch`` command: - -.. code-block:: console - - $ git format-patch -1 --subject-prefix='PATCH v2' - -To add a change log, open the generated email with you favorite text -editor and edit the message body. If there is just one patch, the change -log should go right after ``---`` in the message body (it will be ignored -by ``git am`` then). If there is more than one patch, the change log should -be added to the cover letter. Here is an example of a good change log: - -.. code-block:: console - - Changes in v3: - - Fixed comments as per review by Alex - - Added more tests - Changes in v2: - - Fixed a crash if the user passes invalid options - - Fixed a memory leak at exit - -It is also a good practice to add a reference to the previous version of -your patch set (via a hyperlink or message id). - -.. NOTE:: - - * Do not disagree with the reviewer without providing a good argument - supporting your point of view. - * Do not take every word the reviewer says for granted. Reviewers are - humans too, hence fallible. - * Do not expect that the reviewer will tell you how to do your thing. - It is not their job. The reviewer might suggest alternative ways to - tackle the problem, but in general it is your responsibility. - * Do not forget to update your remote git branch every time you send a - new version of your patch. - * Do follow the guidelines above. If you do not comply, your patches are - likely to be silently ignored. - diff --git a/locale/ru/LC_MESSAGES/dev_guide/developer_guidelines.po b/locale/ru/LC_MESSAGES/dev_guide/developer_guidelines.po index c169de6e16..8c2e7a4a08 100644 --- a/locale/ru/LC_MESSAGES/dev_guide/developer_guidelines.po +++ b/locale/ru/LC_MESSAGES/dev_guide/developer_guidelines.po @@ -240,389 +240,3 @@ msgid "" "Based on [`1 `_] and [`2 `_]." msgstr "" - -msgid "How to submit a patch for review" -msgstr "Как отправить патч на рассмотрение" - -msgid "" -"We don't accept GitHub pull requests. Instead, all patches should be sent as" -" plain-text messages to tarantool-patches@dev.tarantool.org. Please " -"subscribe to our mailing list at " -"https://lists.tarantool.org/mailman/listinfo/tarantool-patches to ensure " -"that your messages are added to the archive." -msgstr "" -"Мы не принимаем запросы на включение в проект на GitHub. Вместо этого все " -"патчи следует отправлять в виде обычного текстового сообщения по адресу " -"tarantool-patches@dev.tarantool.org. Подпишитесь на рассылку " -"https://lists.tarantool.org/mailman/listinfo/tarantool-patches, чтобы " -"убедиться, что ваши сообщения добавляются в архив." - -msgid "**Preparing a patch**" -msgstr "**Подготовка патча**" - -msgid "" -"Once you have committed a patch to your local git repository, you can submit" -" it for review." -msgstr "" -"После коммита патча в локальный репозиторий git вы можете отправить его на " -"рассмотрение." - -msgid "To prepare an email, use ``git format-patch`` command:" -msgstr "" -"Чтобы подготовить сообщение, воспользуйтесь командой ``git format-patch``:" - -msgid "$ git format-patch -1" -msgstr "$ git format-patch -1" - -msgid "" -"It will format the commit at the top of your local git repository as a " -"plain-text email and write it to a file in the current directory. The file " -"name will look like ``0001-your-commit-subject-line.patch``. To specify a " -"different directory, use ``-o`` option:" -msgstr "" -"В результате последний коммит в локальном репозитории git будет " -"отформатирован в виде обычного текстового сообщения в файл в текущей " -"директории. Название файла будет выглядеть так: ``0001-тема-коммита.patch``." -" Чтобы указать другую директорию, используйте опцию ``-o``:" - -msgid "$ git format-patch -1 -o ~/patches-to-send" -msgstr "$ git format-patch -1 -o ~/patches-to-send" - -msgid "" -"Once the patch has been formatted, you can view and edit it with your " -"favorite text editor (after all, it is a plain-text file!). We strongly " -"recommend adding:" -msgstr "" -"После форматирования патча его можно просмотреть и отредактировать в вашем " -"любимом текстовом редакторе (всё-таки это файл с обычным текстом!) Мы " -"настоятельно рекомендуем добавить следующее:" - -msgid "a hyperlink to the branch where this patch can be found at GitHub, and" -msgstr "ссылка на ветку, где можно найти этот патч на GitHub, а также" - -msgid "a hyperlink to the GitHub issue your patch is supposed to fix, if any." -msgstr "ссылку на проблему на GitHub, которую решает ваш патч." - -msgid "" -"If there is just one patch, the change log should go right after ``---`` in " -"the message body (it will be ignored by ``git am`` then)." -msgstr "" -"Если патч всего один, журнал изменений должен идти сразу после ``---`` в " -"теле сообщения (тогда ``git am`` проигнорирует его)." - -msgid "" -"If there are multiple patches you want to submit in one go (e.g. this is a " -"big feature which requires some preparatory patches to be committed first), " -"you should send each patch in a separate email in reply to a cover letter. " -"To format a patch series accordingly, pass the following options to ``git " -"format-patch``:" -msgstr "" -"Если же вы хотите отправить сразу несколько патчей (например, это важная " -"функция, для которой нужны несколько предварительных патчей), каждый из них " -"следует отправлять в отдельном сообщении в ответ на сопроводительное письмо." -" Чтобы соответствующим образом отформатировать серию патчей, передайте " -"следующие опции в ``git format-patch``:" - -msgid "$ git format-patch --cover-letter --thread=shallow HEAD~2" -msgstr "$ git format-patch --cover-letter --thread=shallow HEAD~2" - -msgid "where:" -msgstr "где:" - -msgid "" -"``--cover-letter`` will make ``git format-patch`` generate a cover letter;" -msgstr "" -"``--cover-letter`` заставит ``git format-patch`` сгенерировать " -"сопроводительное письмо;" - -msgid "" -"``--thread=shallow`` will mark each formatted patch email to be sent in " -"reply to the cover letter;" -msgstr "" -"``--thread=shallow`` отметит каждое сообщение с отформатированными патчами, " -"которые следует отправить в ответ на сопроводительное письмо;" - -msgid "" -"``HEAD~2`` (we now use it instead of ``-1``) will make ``git format-patch`` " -"format the first two patches at the top of your local git branch instead of " -"just one. To format three patches, use ``HEAD~3``, and so forth." -msgstr "" -"``HEAD~2`` (мы используем вместо ``-1``) заставит ``git format-patch`` " -"форматировать последние два патча в локальной ветке git, а не один. Чтобы " -"форматировать три патча, используйте ``HEAD~3``, и так далее." - -msgid "" -"After the command has been successfully executed, you will find all your " -"patches formatted as separate emails in your current directory (or in the " -"directory specified via ``-o`` option):" -msgstr "" -"После успешного выполнения этой команды все ваши патчи будут отформатированы" -" в виде отдельных сообщений в текущей директории (или в директории, " -"указанной с помощью опции ``-o``):" - -msgid "" -"0000-cover-letter.patch\n" -"0001-first-commit.patch\n" -"0002-second-commit.patch\n" -"..." -msgstr "" -"0000-cover-letter.patch\n" -"0001-first-commit.patch\n" -"0002-second-commit.patch\n" -"..." - -msgid "" -"The cover letter will have BLURB in its subject and body. You'll have to " -"edit it before submitting (again, it is a plain text file). Please write:" -msgstr "" -"В теме и теле сопроводительного письма будут рекламные аннотации. Вам нужно " -"их отредактировать перед отправкой (опять же, это обычный текст). Просьба " -"указать следующее:" - -msgid "a short series description in the subject line;" -msgstr "короткое описание в теме сообщения;" - -msgid "a few words about each patch of the series in the body." -msgstr "несколько слов о каждом патче в теле сообщения." - -msgid "" -"And don't forget to add hyperlinks to the GitHub issue and branch where your" -" series can be found. In this case you don't need to put links or any " -"additional information to each individual email -- the cover letter will " -"cover everything." -msgstr "" -"Кроме того, не забудьте добавить ссылки на проблему на GitHub и на ветку, " -"где можно найти серию патчей. В таком случае нет необходимости указывать " -"ссылки или дополнительную информацию в каждом отдельном письме, поскольку " -"всё необходимое уже будет в сопроводительном письме." - -msgid "" -"To omit ``--cover-letter`` and ``--thread=shallow`` options, you can add the" -" following lines to your gitconfig:" -msgstr "" -"Чтобы не указывать опции ``--cover-letter`` и ``--thread=shallow``, можно " -"добавить в gitconfig следующие строки:" - -msgid "" -"[format]\n" -" thread = shallow\n" -" coverLetter = auto" -msgstr "" -"[format]\n" -" thread = shallow\n" -" coverLetter = auto" - -msgid "**Sending a patch**" -msgstr "**Отправка патча**" - -msgid "" -"Once you have formatted your patches, they are ready to be sent via email. " -"Of course, you can send them with your favorite mail agent, but it is much " -"easier to use ``git send-email`` for this. Before using this command, you " -"need to configure it." -msgstr "" -"После форматирования патчей их можно отправлять по электронной почте. " -"Конечно, можно воспользоваться и любимым почтовым клиентом, но гораздо проще" -" отправить их с помощью ``git send-email``. Перед использованием команды ее " -"необходимо настроить." - -msgid "" -"If you use a GMail account, add the following code to your ``.gitconfig``:" -msgstr "" -"Если используется учетная запись GMail, добавьте следующий код в " -"``.gitconfig``:" - -msgid "" -"[sendemail]\n" -" smtpencryption = tls\n" -" smtpserver = smtp.gmail.com\n" -" smtpserverport = 587\n" -" smtpuser = your.name@gmail.com\n" -" smtppass = topsecret" -msgstr "" -"[sendemail]\n" -" smtpencryption = tls\n" -" smtpserver = smtp.gmail.com\n" -" smtpserverport = 587\n" -" smtpuser = your.name@gmail.com\n" -" smtppass = topsecret" - -msgid "For mail.ru users, the configuration will be slightly different:" -msgstr "Для пользователей mail.ru настройки будут слегка отличаться:" - -msgid "" -"[sendemail]\n" -" smtpencryption = ssl\n" -" smtpserver = smtp.mail.ru\n" -" smtpserverport = 465\n" -" smtpuser = your.name@mail.ru\n" -" smtppass = topsecret" -msgstr "" -"[sendemail]\n" -" smtpencryption = ssl\n" -" smtpserver = smtp.mail.ru\n" -" smtpserverport = 465\n" -" smtpuser = your.name@mail.ru\n" -" smtppass = topsecret" - -msgid "" -"If your email account is hosted by another service, consult your service " -"provider about your SMTP settings." -msgstr "" -"Если ваша учетная запись электронной почты находится на другом ресурсе, " -"уточните SMTP-настройки у поставщика услуг." - -msgid "Once configured, use the following command to send your patches:" -msgstr "После настройки используйте следующую команду для отправки патчей:" - -msgid "$ git send-email --to tarantool-patches@dev.tarantool.org 00*" -msgstr "$ git send-email --to tarantool-patches@dev.tarantool.org 00*" - -msgid "" -"(``00*`` wildcard will be expanded by your shell to the list of patches " -"generated at the previous step.)" -msgstr "" -"(подстановочный символ ``00*`` будет распространяться на список патчей, " -"сгенерированных в предыдущем шаге.)" - -msgid "" -"If you want someone in particular to review your patch, add them to the list" -" of recipients by passing ``--to`` or ``--cc`` once per each recipient." -msgstr "" -"Если вы бы хотели, чтобы определенный человек рассматривал ваш патч, " -"добавьте его в список получателей, передав ``--to`` или ``--cc`` для каждого" -" получателя." - -msgid "" -"It is useful to check that ``git send-email`` will work as expected without " -"sending anything to the world. Use ``--dry-run`` option for that." -msgstr "" -"Неплохо проверить, что ``git send-email`` будет работать должным образом, не" -" отправив ничего на весь мир. Для этого воспользуйтесь опцией ``--dry-run``." - -msgid "**Review process**" -msgstr "**Процесс рассмотрения**" - -msgid "" -"After having sent your patches, you just wait for a review. The reviewer " -"will send their comments back to you in reply to the email that contains the" -" patch that in their opinion needs to be fixed." -msgstr "" -"После отправки патчей вы ожидаете их рассмотрения. Редактор отправит свои " -"комментарии в ответ на сообщение с патчем, который нуждается в доработке, по" -" его мнению." - -msgid "" -"Upon receiving an email with review remarks, you carefully read it and reply" -" about whether you agree or disagree with. Please note that we use the " -"interleaved reply style (aka \"inline reply\") for communications over " -"email." -msgstr "" -"Получив электронное письмо с примечаниями, вы внимательно читаете его и " -"отвечаете, согласны вы или нет. Обратите внимание, что мы используем стиль " -"ответа с чередованием (он же \"встроенный ответ\") в сообщениях электронной " -"почты." - -msgid "" -"Upon reaching an agreement, you send a fixed patch in reply to the email " -"that ended the discussion. To send a patch, you can either attach a plain " -"diff (created by ``git diff`` or ``git format-patch``) to email and send it " -"with your favorite mail agent, or use ``--in-reply-to`` option of ``git " -"send-email`` command." -msgstr "" -"Достигнув соглашения, вы отправляете доработанный патч в ответ на последнее " -"сообщение в обсуждении. Чтобы отправить патч, вы можете либо вложить простой" -" diff (созданный с помощью ``git diff`` или ``git format-patch``) в " -"сообщение электронной почте и отправить его с помощью вашего любимого " -"почтового клиента, либо использовать опцию ``--in-reply-to`` команды ``git " -"send-email``." - -msgid "" -"If you feel that the accumulated change set is large enough to send the " -"whole series anew and restart the review process in a different thread, you " -"generate the patch email(s) again with ``git format-patch``, this time " -"adding v2 (then v3, v4, and so forth) to the subject and a change log to the" -" message body. To modify the subject line accordingly, use the ``--subject-" -"prefix`` option to ``git format-patch`` command:" -msgstr "" -"Если вы считаете, что общий набор изменений достаточно велик, чтобы " -"отправить всю серию заново и перезапустить процесс рассмотрения в рамках " -"нового обсуждения, вы снова генерируете сообщения с патчами с помощью ``git " -"format-patch``, на этот раз добавив v2 (затем v3, v4 и так далее) в тему и " -"журнал изменений в тело сообщения. Чтобы соответствующим образом изменить " -"тему сообщения, используйте опцию ``--subject-prefix`` в команде ``git " -"format-patch``:" - -msgid "$ git format-patch -1 --subject-prefix='PATCH v2'" -msgstr "$ git format-patch -1 --subject-prefix='PATCH v2'" - -msgid "" -"To add a change log, open the generated email with you favorite text editor " -"and edit the message body. If there is just one patch, the change log should" -" go right after ``---`` in the message body (it will be ignored by ``git " -"am`` then). If there is more than one patch, the change log should be added " -"to the cover letter. Here is an example of a good change log:" -msgstr "" -"Чтобы добавить журнал изменений, откройте созданное сообщение с помощью " -"любимого текстового редактора и отредактируйте тело сообщения. Если патч " -"всего один, журнал изменений должен идти сразу после ``---`` в теле " -"сообщения (тогда ``git am`` проигнорирует его). Если патчей несколько, " -"журнал изменений следует добавить в сопроводительное письмо. Хороший пример " -"журнала изменений:" - -msgid "" -"Changes in v3:\n" -" - Fixed comments as per review by Alex\n" -" - Added more tests\n" -"Changes in v2:\n" -" - Fixed a crash if the user passes invalid options\n" -" - Fixed a memory leak at exit" -msgstr "" -"Changes in v3:\n" -" - Fixed comments as per review by Alex\n" -" - Added more tests\n" -" Changes in v2:\n" -" - Fixed a crash if the user passes invalid options\n" -" - Fixed a memory leak at exit" - -msgid "" -"It is also a good practice to add a reference to the previous version of " -"your patch set (via a hyperlink or message id)." -msgstr "" -"Также правильно будет добавить ссылку на предыдущую версию набора патчей " -"(гиперссылку или идентификатор сообщения)." - -msgid "" -"Do not disagree with the reviewer without providing a good argument " -"supporting your point of view." -msgstr "Не спорьте с редактором без веских аргументов в свою поддержку." - -msgid "" -"Do not take every word the reviewer says for granted. Reviewers are humans " -"too, hence fallible." -msgstr "" -"Не принимайте любые слова редактора без доказательств. Редакторы -- тоже " -"люди, которые могут ошибаться." - -msgid "" -"Do not expect that the reviewer will tell you how to do your thing. It is " -"not their job. The reviewer might suggest alternative ways to tackle the " -"problem, but in general it is your responsibility." -msgstr "" -"Не ждите, что редактор скажет вам, как что делать. Это не их работа. " -"Редактор может предложить пути решения проблемы, но вообще говоря, это ваша " -"обязанность." - -msgid "" -"Do not forget to update your remote git branch every time you send a new " -"version of your patch." -msgstr "" -"Не забывайте обновлять удаленную ветку git каждый раз, когда отправляете " -"новую версию патча." - -msgid "" -"Do follow the guidelines above. If you do not comply, your patches are " -"likely to be silently ignored." -msgstr "" -"Соблюдайте вышеуказанные рекомендации. Если вы не будете их соблюдать, ваши " -"патчи могут быть молча проигнорированы."