[devel] Путаница в терминологии и названиях в документации

[Aleksey Cheusov <vle@gmx.net>]

Привет всем. Заделом для этих замечаний и предложений явилась короткая offlist дискуссия с mike@
о давнишнем разделе git.alt на части. То, что ниже -- немного дискуссий на эту же тему в телеграм
канале и мой ответ Черепанову. Конструктив -- в двух первых моих постах в телеграме.
В принципе, дальше уже лирика, разжевывания и примеры (скукота).

Aleksey Cheusov, [17.05.20 16:11]
Риторический вопрос. А зачем, когда распиливали git.alt на части, не сделали так: git.alt оставить как
набор git репозиториев (на что компонент git в названии как бы и намекает), а сборочницу назвать
просто и банально build.alt (о чем и говорит компонент build в названии). Вместо этого ввели две
непонятных сущности на букву g. Если что, это идея Шигорина, я не сам придумал, но она мне кажется
Очень Логичной. gitery и gyle -- просто лишние названия, которые все усложняют. Кстати, в некоторых
Вики сборочницу ещё называют girar. В общем, кто в лес, кто по дрова, а сущности
всего лишь две: место, где хранятся репы, и сборочница

Wladmis, [17.05.20 16:20]
И всё ещё чуть-чуть сложнее.

Aleksey Cheusov, [17.05.20 16:23]
git.altlinux.org:2222 -- репы, build.altlinux.org:2222 -- сборочница. Чего-то не хватает?
Если эти порты заняты, можно взять другие

Aleksey Cheusov, [17.05.20 16:37]
Рекомендовать настройки .ssh/config можно было *бы* такие: git.alt и build.alt,
что я у себя и сделал. Очень просто, и очень понятно.

=============== Если мыль не ясна, читайте дальше. Конкструктив уже был :-) ==================

Anton Shevtsov, [17.05.20 18:02]
Поддерживаю. Gitery,girar,gyle.. усложнено все

Андрей Черепанов, [17.05.20 19:45]
[In reply to Anton Shevtsov]
Искусство не бывает простым. 😁

Aleksey Cheusov, [17.05.20 22:16]
[In reply to Андрей Черепанов]
А по сути? 😉

Андрей Черепанов, [18.05.20 08:44]
[In reply to Aleksey Cheusov]
По сути что? Именование серверов не является в Альте утилитарным, а подчиняется традиции, сложившейся исторически.

Aleksey Cheusov, [18.05.20 09:06]
На свое рац. предложение я рассчитывал получить сколь-нибудь рациональный
аргументированный ответ, а не "так повелось издревле".
Ответа "и все ещё чуть-чуть сложнее" я вообще не понял. То есть, в принципе уже ничего

Андрей Черепанов, [18.05.20 09:08]
[In reply to Aleksey Cheusov]
Рацпредложение в чём? В именовании серверов? Каждый может обозначить в ~/.ssh/config как угодно.
У меня вообще builder/git.alt. Не вижу смысла прикапываться к единовременной настройке.

Wladmis, [18.05.20 11:32]
[In reply to Aleksey Cheusov]
Это было риторическое замечание, но таки всё действительно чуть-чуть сложнее. Как, например,
часть (чуть ли не большая) пакетов до сих пор собирается из sourcerpm. А girar — это название
самой сборочницы (т.е., название программного обеспечения), а не самого сервера сборки.

Aleksey Cheusov, [18.05.20 11:37]
[In reply to Wladmis]
Насчёт girar я в курсе. Мой посыл в том, что документация оставляет желать лучшего. Отчасти это связано
с перегруженной на пустом месте терминологией. Перед лицом своих товарищей я обещал альтовцам
"обращать внимание своим свежим взглядом на всякие мелочи"(С) и я это делаю.
Что делать с традициями, уходящими в глубь веков, решать вам 😉

Андрей Черепанов, [18.05.20 16:10]
[In reply to Aleksey Cheusov]
Вот и укажите на конкретные проблемы на указанных страницах документации.

=========================================================================
Путаница #1:
  https://www.altlinux.org/Git.alt:

  "Выполняемые задачи
    Хостинг git-репозиториев, заточенный под нужды разработчиков Sisyphus
    Управление правами доступа к сборке пакетов в Sisyphus и другие бранчи
    Сборка пакетов в Sisyphus и другие бранчи из gear-репозиториев и SRPM-пакетов, располагающихся на нём самом"(c)

git.alt не может выполнять одновременно две задачи -- управлением gear
репозиториями и сборкой пакетов, поскольку вы распилили этот сервис на
два примерно : лет 5 назад. Один отвечает за сборку, второй -- за гит репы.
Здесь под git.alt имеется ввиду и то и другое месте, но
тогда это печально, поскольку в других статьях вики имя git.alt нам
явно рекомендуется повесить на сервис управления gear/git репозиториями.

=========================================================================
Путаница #2:
  Там же.

  "Powered by
  git.alt работает под управлением комплекса инструментов girar и girar-builder."(c)

  Обоснование выше. girar-builder -- это сборочница, а girar -- это управлялка репами.

Названия girar и girar-builder на этом этапе начинающему
мэнтейнеру AltLinux не говорят ни о чем. Они ему и не нужны. Ему
интересны ssh сервисы, и вот с ними его нужно и познакомить.
Я бы убрал их из документации. Тем не менее, запомним, что girar -- это
управление git репозиториями.

=========================================================================
Путаница #3:
https://www.altlinux.org/Git.alt/%D0%A1%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA#acl_show

  "С 01.08.2015 г. для работы с git репозиторием надо настроить доступ к двум серверам : gitery.altlinux.org (gitery) и gyle.altlinux.org (girar)."(c)

  Здесь вводятся два новых ненужных слова: gitery, gyle. Кроме того
  girar (выше написано, что это управлялка git репозиториями)
  относится уже к сборочнице, хотя тул для нее называется girar-build,
  а girar -- это управлялка git репозиториями.

Там же, чуть ниже
  git.alt (gitery)
  girar (gyle)

  См. выше по аповоду запутанной терминологии. Кроме того в из "путаницы #1"
  мы помним, что git.alt -- это сборное понятие, обозначающее *и* управлялку репами
  *и* сборочницу.

=========================================================================
Путаница #3:
https://www.altlinux.org/Git.alt/%D0%A1%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA#acl_show

   "Web-интерфейс Располагается по адресу http://git.altlinux.org/"

   Выше мы сказали, что web interface -- это git.alt, который мы
   назначили на gitery.altlinux.org. Конечно, я знаю разницу между
   службами ssh:// и http://, но и этой путаницы можно было бы
   избежать, если бы репы, доступные по ssh:// и действительно web
   interface http:// располагались на одном сайте -- git.altlinux.org,
   и висели на разных портах, как это обычно и делается.

=========================================================================
Путаница #4:
https://www.altlinux.org/Git.alt/FAQ
   "успешно собранные из gear-репозиториев пакеты сразу публикуются на /gears (он же git.altlinux.org::gears)"

   Выше было сказано, что пользовательские gear репы находятся на
   хосте gitery.altlinux.org. Окончательные репы Сизифа, как я
   понимаю -- на git.altlinux.org. Не то, чтобы это ошибка, но
   запутывает немного. Сходим смеху ради на
   http://git.altlinux.org/people/ -- все доступно, зачем тогда понадобился
   gitery.altlinux.org? http://git.altlinux.org/gears/ -- тоже работает.
   По http:// к репам добраться разработчиков можно, а по ssh -- зачем-то
   понадобился gitery.

=========================================================================
Путаница #5:
https://www.altlinux.org/Сборка_пакета_с_нуля#Отправка_в_git.alt

   "Отправка в git.alt"(c)

   Этот кувшин пуст(C). Если по несчастливой случайности вы наяндексили
   именно эту страницу, вы расстроитесь.

   В целом эта страница не отвечает своему заголовку. Запакетить
   какой-нибудь пакет с нуля она мне не позволит.

=========================================================================
Путаница #6:
https://www.altlinux.org/Краткое_руководство_по_сборке_пакета

   "git clone git://git.altlinux.org/people/dottedmag/packages/keyjnote.git"(c)

   Именно этот пример нерабочий, надежнее было бы какой-то фейковый
   пакет положить, и никогда никуда не заливать, скажем
   /people/mike/packages/gnuhello.git или что-то в этом духе.

=========================================================================
Путаница #7:
https://www.altlinux.org/Краткое_руководство_по_сборке_пакета#Сборка

   Здесь нам советуют для сборки использовать "gear-hsh $TMP/"

а вот здесь https://www.altlinux.org/О_стратегии_сборки_RPM_пакетов#Сборка

   скрипт какого-то парня. В чем разница без прочтения вороха
   документации -- совершенно не ясно. Этот ворох я еще не осилил.

=========================================================================
Путаница #8:
https://www.altlinux.org/О_стратегии_сборки_RPM_пакетов

   Вот здесь очень часто для редактирования команды используется конструкция с nohup:

   nohup medit /etc/hasher-priv/system 1>/dev/null 2>/dev/null &

   Я знаю, что такое nohup, но здесь он точно не нужен. Возможно, он
   попал сюда только потому, что такая схема *нравится* автору этой wiki
   страницы. Но, поскольку wiki в AltLinux не разделены на
   "Официальные" и "Какие-то люди написали", у меня в этом месте
   возникают вопросы.