diff options
Diffstat (limited to 'documentation/content/ru/books/porters-handbook/upgrading/_index.adoc')
| -rw-r--r-- | documentation/content/ru/books/porters-handbook/upgrading/_index.adoc | 181 |
1 files changed, 122 insertions, 59 deletions
diff --git a/documentation/content/ru/books/porters-handbook/upgrading/_index.adoc b/documentation/content/ru/books/porters-handbook/upgrading/_index.adoc index 863bd4ad3b..c6f3b2a5bb 100644 --- a/documentation/content/ru/books/porters-handbook/upgrading/_index.adoc +++ b/documentation/content/ru/books/porters-handbook/upgrading/_index.adoc @@ -1,11 +1,13 @@ --- -title: Глава 10. Обновление отдельного порта -prev: books/porters-handbook/testing +description: 'Обновление порта FreeBSD' next: books/porters-handbook/security -showBookMenu: true -weight: 10 params: - path: "/books/porters-handbook/upgrading/" + path: /books/porters-handbook/upgrading/ +prev: books/porters-handbook/testing +showBookMenu: true +tags: ["upgrading", "port", "git"] +title: 'Глава 11. Обновление отдельного порта' +weight: 11 --- [[port-upgrading]] @@ -16,7 +18,7 @@ params: :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 10 +:sectnumoffset: 11 :partnums: :source-highlighter: rouge :experimental: @@ -46,32 +48,37 @@ toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] -Если вы заметите, что ваш порт устарел по сравнению с последней авторской версией, первым делом вы должны получить самую последнюю версия порта. Вы можете найти их в каталоге [.filename]#ports/ports-current# на зеркальных FTP-серверах FreeBSD. Однако если вы работаете с достаточно большим количеством портов, наверное, будет проще использовать Subversion или man:portsnap[8] для поддержания всей коллекции портов в актуальном состоянии, как это описано в extref:{handbook}ports/[Руководстве, ports-using]. К тому же это даст возможность отслеживать все зависимости портов. +Когда порт не является самой последней версией, доступной от авторов, обновите локальную рабочую копию [.filename]#/usr/ports#. Возможно, порт уже был обновлён до новой версии. -На следующем шаге необходимо выяснить, нет ожидает ли уже это обновление своей очереди. Для этого у вас есть две возможности. Существует интерфейс к http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[базе данных сообщений о проблемах FreeBSD (PR)] (известной также как `GNATS`) с поисковыми возможностями. Выберите из выпадающего списка `ports` и введите название порта. +При работе с большим количеством портов, вероятно, будет проще использовать Git для поддержания всей коллекции портов в актуальном состоянии, как описано в extref:{handbook}ports[Использование коллекции портов, ports-using]. Это также позволит отслеживать все зависимости портов. -Однако иногда люди забывают поместить название порта в поле Synopsis в точном виде. В таком случае вы можете воспользоваться <<portsmon,Системой мониторинга портов FreeBSD>> (которая известна также как `portsmon`). В рамках этой системы делается попытка классифицировать PR, касающиеся портов, по имени порта. Для поиска PR, относящихся к определённому порту, используйте механизм http://portsmon.FreeBSD.org/portoverview.py[Просмотра по одному порту]. +Следующий шаг — проверить, есть ли уже ожидающее обновление. Для этого есть два варианта. Доступен поиск в https://bugs.freebsd.org/search/[Сообщения о проблемах (PR) или база данных ошибок FreeBSD]. Выберите `Ports & Packages` в меню множественного выбора `Product` и введите название порта в поле `Summary`. Если таких отложенных PR не существует, то на следующем этапе следует послать сообщение электронной почты человеку, поддерживающему порт, который выдаётся по команде `make maintainer`. Этот человек может уже работать над обновлением, или иметь причину не обновлять порт прямо сейчас (например, из-за проблем со стабильностью функционирования новой версии); вам нет нужды дублировать их работу. Заметьте, что неподдерживаемые порты перечисляются с адресом сопровождающего `ports@FreeBSD.org`, который является всего лишь адресом общего списка рассылки, так что отправка туда сообщений, скорее всего, в данном случае не поможет. Если сопровождающий просит вас выполнить обновление, либо сопровождающий отсутствует, то у вас появляется шанс помочь FreeBSD, приготовив обновление самим! Пожалуйста, делайте это с использованием команды man:diff[1] в основной системе. -Чтобы создать подходящий `diff` для одного патча, скопируйте файл, который нужно пропатчить, в _something.orig_, сохраните ваши изменения в _something_, а затем создайте ваше патч: +Чтобы создать подходящий `diff` для одного патча, скопируйте файл, который нужно пропатчить, в [.filename]#something.orig#, сохраните ваши изменения в [.filename]#something#, а затем создайте ваше патч: -[source,shell] +[source, shell] .... % diff -u something.orig something > something.diff .... -В противном случае, вам следует воспользоваться методом `svn diff` (<<svn-diff>>), либо скопировать содержимое порта в отдельный каталог и применить результат рекурсивной команды man:diff[1] между новым и старым каталогами порта (например, если каталог с модифицированным портом называется [.filename]#superedit#, а оригинальный, совпадающий с находящимся в нашем дереве портов, [.filename]#superedit.bak#, то сохраните результат выполнения команды `diff -ruN superedit.bak superedit`). Подойдёт как унифицированный, так и контекстный дифф, однако коммиттеры портов обычно предпочитают унифицированный формат. Отметьте использование опции `-N`-это одобряемый способ заставить diff корректно работать в случае добавления новых файлов или удаления старых. Перед тем, как посылать нам diff-файл, пожалуйста, проверьте его, чтобы убедиться в значимости всех внесённых изменений. (В частности, убедитесь, что вы очистили рабочие каталоги командой `make clean`). +В противном случае используйте метод `git diff` (crossref:upgrading[git-diff, Использование Git для создания патчей]) или скопируйте содержимое порта в совершенно другой каталог и используйте результат рекурсивного вывода man:diff[1] для новых и старых каталогов портов (например, если изменённый каталог порта называется [.filename]#superedit#, а исходный находится в нашем дереве как [.filename]#superedit.bak#, сохраните результат выполнения `diff -ruN superedit.bak superedit`). Подойдёт как унифицированный, так и контекстный diff, но коммиттеры портов обычно предпочитают унифицированные diff. Обратите внимание на использование опции `-N` — это общепринятый способ заставить diff корректно обрабатывать случаи добавления новых файлов или удаления старых. Перед отправкой diff, пожалуйста, проверьте вывод, чтобы убедиться, что все изменения имеют смысл. (В частности, не забудьте сначала очистить рабочие каталоги с помощью `make clean`). -Для упрощения повторяющихся операций с файлами заплаток вы можете воспользоваться скриптом [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Перед тем, как его запускать, пожалуйста, прочтите [.filename]#/usr/ports/Tools/scripts/README.patchtool#. +[NOTE] +==== +Если некоторые файлы были добавлены, скопированы, перемещены или удалены, добавьте эту информацию в отчёт о проблеме, чтобы коммиттер, принимающий патч, знал, какие команды man:git[1] нужно выполнить. +==== + +Для упрощения стандартных операций с файлами исправлений используйте `make makepatch`, как описано в crossref:slow-porting[slow-patch,Применение партчей]. Существуют и другие инструменты, например [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Перед его использованием прочтите [.filename]#/usr/ports/Tools/scripts/README.patchtool#. Если порт никем не поддерживается, а вы активно его используете, пожалуйста, подумайте над тем, чтобы добровольно стать его сопровождающим. Во FreeBSD имеется более 4000 портов без поддержки, и это как раз та область, где всегда нужны добровольцы. (Детальное описание обязанностей сопровождающего можно найти в разделе extref:{developers-handbook}[Руководства Разработчика, POLICIES-MAINTAINER].) -Лучше всего послать нам diff-файл, включив его в посылку по команде man:send-pr[1] (категория `ports`). Если вы сопровождаете порт, обязательно поместите текст `[maintainer update]` в начале строки описания и задайте в поле "Class" вашего PR строчку `maintainer-update`. В противном случае в поле "Class" вашего PR должно быть указано `change-request`. Будьте добры, в сообщении отметьте все добавленные или удалённые файлы, так как они будут непосредственно указаны man:svn[1] при выполнении операции коммита. Если diff-файл имеет размер, превышающий 20КБ, сожмите его и обработайте утилитой uuencode; в противном случае просто включите его как есть в PR. +Для отправки diff используйте https://bugs.freebsd.org/submit/[форму отправки багов] (продукт `Ports & Packages`, компонент `Individual Port(s)`). Всегда указывайте категорию с именем порта, за которой следует двоеточие и краткое описание проблемы. Примеры: `_категория/имя_порта_: _добавить опцию FOO_`; `_категория/имя_порта_: _Обновление до X.Y_`. Упоминайте в сообщении все добавленные или удалённые файлы, так как они должны быть явно указаны в man:git[1] при выполнении коммита. Не сжимайте и не кодируйте diff. -Прежде чем пользоваться man:send-pr[1] просмотрите раздел о extref:{problem-reports}[Написании сообщений о проблемах, pr-writing] в статье о Сообщениях об ошибках. Он содержит гораздо больше информации о том, как писать полезные сообщения о проблемах. +Прежде чем отправить сообщение об ошибке, ознакомьтесь с разделом extref:{problem-reports}[Написание отчета о проблеме, pr-writing] в статье "Отчеты о проблемах". В нем содержится гораздо больше информации о том, как составлять полезные отчеты о проблемах. [IMPORTANT] ==== @@ -80,82 +87,100 @@ endif::[] [NOTE] ==== -Повторяем еще раз - для посылки обновлений существующих портов используйте утилиту man:diff[1], а не man:shar[1]! Это поможет понять коммиттерам портов, что именно было изменено. +Пожалуйста, используйте man:diff[1] или `git diff` для создания обновлений существующих портов. Другие форматы включают весь файл и делают невозможным увидеть только изменённые части. Если различия не включены, всё обновление может быть проигнорировано. ==== Теперь, когда вы проделали всё это, прочитайте о том, как поддерживать актуальное состояние, в crossref:keeping-up[keeping-up, Актуализация]. -[[svn-diff]] -== Использование Subversion для создания патчей +[[git-diff]] +== Использование Git для создания патчей -По возможности присылайте исправления в формате man:svn[1] diff. В таком виде их проще использовать по сравнению с разницей между "старым и новым" каталогами. Так проще увидеть изменения и обновить их в случае, если что-нибудь изменилось в Коллекции Портов с тех пор, как вы начали работу, либо если коммиттер просит что-то исправить. +Когда это возможно, пожалуйста, предоставляйте патч или diff с помощью man:git[1]. Их проще обрабатывать, чем различия между «новым и старым» каталогом. Так легче увидеть, что изменилось, и обновить diff, если что-то было изменено в Коллекции портов с момента начала работы над ней, или если коммиттер просит что-то исправить. Кроме того, патч, созданный с помощью man:git-format-patch[1] или man:git-diff[1], можно легко применить с помощью man:git-am[1] или man:git-apply[1], что сэкономит время коммиттера. Наконец, git-патч, созданный man:git-format-patch[1], включает информацию об авторе и сообщения коммитов. Они будут записаны в лог репозитория, и это рекомендуемый способ отправки ваших изменений. -[source,shell] +[source, shell] .... -% cd ~/my_wrkdir <.> -% svn co https://svn0.us-west.FreeBSD.org/ports/head/dns/pdnsd <.> -% cd ~/my_wrkdir/pdnsd +% git clone https://git.FreeBSD.org/ports.git ~/my_wrkdir <.> <.> +% cd ~/my_wrkdir .... <.> Это может быть где угодно; место, в котором производится построение портов, не привязано к [.filename]#/usr/ports/#. -<.> https://svn0.us-west.FreeBSD.org/[svn0.us-west.FreeBSD.org] - это общедоступный сервер Subversion. Выберите ближайшее зеркало и проверьте сертификат зеркалирующего сервера на наличие в перечне extref:{handbook}mirrors/[зеркалирующих сайтов Subversion, svn-mirrors]. +<.> https://git.FreeBSD.org/[git.FreeBSD.org] — это публичный Git-сервер FreeBSD. Подробнее см. в extref:{handbook}mirrors[таблице URL-репозиториев FreeBSD Git, git-url-table]. -Находясь в рабочем каталоге, вносите любые изменения, которые обычно делают для порта. При добавлении или удалении файла используйте `svn` для отслеживания этих изменений: +Находясь в каталоге порта, внесите необходимые изменения. Если требуется добавить, переместить или удалить файл, используйте `git` для отслеживания этих изменений: -[source,shell] +[source, shell] .... -% svn add new_file -% svn remove deleted_file +% git add new_file +% git mv old_name new_name +% git rm deleted_file .... -Убедитесь, что вы проверяете порт в соответствии с рекомендуемым порядком проверки, описанным в crossref:quick-porting[porting-testing, Тестирование порта] и crossref:quick-porting[porting-portlint, Проверка вашего порта утилитой `portlint`]. +Убедитесь, что проверили порт, используя контрольный список в crossref:quick-porting[porting-testing,Тестирование порта] и crossref:quick-porting[porting-portlint,Проверка порта с помощью `portlint`]. + +Также обновите ссылку на контрольную сумму в distinfo с помощью `make makesum`. -[source,shell] +Прежде чем создавать патч, загрузите последнюю версию репозитория и перебазируйте изменения поверх неё. Внимательно следите за выводом и следуйте ему. Если какие-либо файлы не удалось перебазировать, это означает, что исходные файлы изменились во время вашего редактирования, и конфликты необходимо разрешить вручную. + +[source, shell] .... -% svn status -% svn update <.> +% git fetch origin main +% git rebase origin/main .... -<.> Эта команда попытается выполнить слияние различий между вашим патчем и текущей версией репозитория; внимательно проверьте полученный вывод. Буква перед названием каждого файла означает тип изменения, сделанного с этим файлом. Для получения полного списка смотрите <<table-svn-up>>. +Проверьте изменения, подготовленные для исправления: -[[table-svn-up]] -.Префиксы файлов для Subversion Update -[cols="1,1", frame="none"] -|=== -|U -|Файл обновлен без проблем. +[source, shell] +.... +% git status +% git diff --staged +.... -|G -|Файл обновлен без проблем (вы увидите это только при работе с удаленным репозиторием). +Последний шаг — создать унифицированный diff или патч изменений: -|M -|Файл с локальными изменениями, слияние выполнено без конфликтов. +Для создания патча с помощью man:git-format-patch[1]: +[source, shell] +.... +% git checkout -b my_branch +% git commit +% git format-patch main +.... -|C -|Файл с локальными изменениями, слияние выполнено с конфликтами. -|=== +Это создаст файл исправления с именем вида `0001-foo.patch`. Это предпочтительный способ, так как он включает идентификацию автора, а также удобнее, когда вы делаете серию изменений, которые не должны объединяться вместе. -Если в результате выполнения `svn update` отображается `C`, то это означает, что что-то изменилось в репозитории Subversion и man:svn[1] не смогла выполнить слияние локальных изменений с полученными из репозитория. В любом случае никогда не помешает просмотреть изменения, поскольку man:svn[1] ничего не знает о том, каким должен быть порт, поэтому эта команда может (и, вероятно, будет) делать слияние тех изменений, которые не имеют смысла. +Или для создания унифицированного diff с помощью man:git-diff[1]: +[source, shell] +.... +% git diff --staged > ../`make -VPKGNAME`.diff +.... +Это создаст файл с различиями с именем вида `foo-1.2.3.diff`. Здесь `foo` заменяется на первую строку сообщения коммита, то есть на тему сообщения коммита. -Последним шагом является создание унифицированного man:diff[1] для полученных изменений: +После создания патча вы можете переключиться на основную ветку для начала других разработок. +[source, shell] +.... +% git checkout main +.... -[source,shell] +После принятия и слияния патча вы можете удалить локальную ветку разработки, если хотите: +[source, shell] .... -% svn diff > ../`basename ${PWD}`.diff +% git branch -D my_branch .... [NOTE] ==== -Информация о любых удаляемых файлов должна быть явным образом указана в PR, поскольку необходимость в удалении файла для коммиттера может быть неочевидна. +Если файлы были добавлены, перемещены или удалены, укажите использованные команды man:git[1] `add`, `mv` и `rm`. Команда `git mv` должна быть выполнена до применения патча. Команды `git add` или `git rm` должны быть выполнены после применения патча. ==== -Присылайте свои патчи в соответствии с руководством, описанном в <<port-upgrading>>. +Отправьте исправление, следуя extref:{problem-reports}[рекомендациям по отправке отчетов о проблемах, pr-writing]. [[moved-and-updating-files]] -== Файлы [.filename]#UPDATING# и [.filename]#MOVED# +== UPDATING и MOVED + +[[moved-and-updating-updating]] +=== /usr/ports/UPDATING -Если при обновлении порта требуются специальные шаги, такие как изменение файлов конфигурации или запуск специальной программы, то вам следует это задокументировать в файле [.filename]#/usr/ports/UPDATING#. Формат записи в этом файле приводится ниже: +Если обновление порта требует специальных действий, таких как изменение конфигурационных файлов или запуск определённой программы, это должно быть задокументировано в данном файле. Формат записи в этом файле следующий: [.programlisting] .... @@ -166,17 +191,55 @@ YYYYMMDD: Special instructions .... -Если вы включаете точные инструкции portmaster или portupgrade, пожалуйста, убедитесь в правильном экранировании символов внутри командной оболочки. +[TIP] +==== -Файл [.filename]#/usr/ports/MOVED# содержит записи об удалённых или перемещённых портах. Каждая строка в этом файле состоит из полей: название порта, место, куда он был перемещён, дата и причина перемещения. Если порт был удалён, то поле, указывающее новое место, может оставаться незаполненным. Поля должны разделяться символом `|` (pipe), как это показано ниже: +При включении точных инструкций для portmaster, portupgrade и/или pkg, убедитесь в правильности экранирования в shell. Например, _не_ используйте: + +[source, shell] +.... +# pkg delete -g -f docbook-xml* docbook-sk* docbook[2345]??-* docbook-4* +.... + +Как показано, команда будет работать только с bourne-оболочками. Вместо этого используйте форму, приведённую ниже, которая будет работать как с bourne-оболочкой, так и с c-оболочкой: + +[source, shell] +.... +# pkg delete -g -f docbook-xml\* docbook-sk\* docbook\[2345\]\?\?-\* docbook-4\* +.... + +==== + +[NOTE] +==== +Рекомендуется, чтобы строка AFFECTS содержала glob-выражение, соответствующее всем портам, затронутым записью, чтобы автоматизированные инструменты могли максимально легко её обработать. Если обновление касается всех существующих версий BIND 9, содержимое `AFFECTS` должно быть `users of dns/bind9*`, и оно _не должно_ быть `users of BIND 9` +==== + +[[moved-and-updating-moved]] +=== /usr/ports/MOVED + +Этот файл используется для перечисления перемещённых или удалённых портов. Каждая строка в файле состоит из названия порта, места, куда порт был перемещён, даты и причины. Если порт был удалён, раздел с указанием места перемещения может быть оставлен пустым. Каждый раздел должен быть отделён символом `|` (вертикальная черта), например: [.programlisting] .... old name|new name (blank for deleted)|date of move|reason .... -Дату следует вводить в формате `YYYY-MM-DD`. Новые записи следует добавлять в конец файла в хронологическом порядке. +Дата должна быть введена в формате `ГГГГ-ММ-ДД`. Новые записи добавляются в конец списка, чтобы сохранить его в хронологическом порядке, при этом самая старая запись находится в начале списка. + +Если порт был удален, но затем восстановлен, удалите строку в этом файле, которая указывает, что он был удален. + +Если порт был переименован, а затем переименован обратно в исходное имя, добавьте новую запись с промежуточным именем для старого имени и удалите старую запись, чтобы не создавать цикл. + +[NOTE] +==== +Любые изменения должны быть проверены с помощью `Tools/scripts/MOVEDlint.awk`. -Если порт был перемещён, но в дальнейшем восстановлен на прежнем месте, удалите в этом файле строку, содержащую информацию о перемещении. +Если используется каталог портов, отличный от [.filename]#/usr/ports#, следует указать: -Полученные изменения можно проверить командой `Tools/scripts/MOVEDlint.awk`. +[source, shell] +.... +% cd /home/user/ports +% env PORTSDIR=$PWD Tools/scripts/MOVEDlint.awk +.... +==== |