Git очень мощный инструмент, который практически каждый разработчик должен использовать ежедневно, но для большинства из нас git сводится к нескольким командам: pull commit push. Однако, чтобы быть эффективным, продуктивным и обладать всей мощью git, необходимо знать ещё несколько команд и трюков. Итак, в этой статье мы исследуем функции git, которые просто запомнить, применять и настроить, но которые могут сделать ваше время с git гораздо более приятным.

Прокачиваем базовый рабочий процесс

Прежде чем мы воспользуемся даже самыми базовыми командами pull, commit и push, необходимо выяснить, что происходит с нашими ветками и изменёнными файлами. Для этого можно воспользоваться git log довольно известной командой, хотя не все знают, как сделать его вывод на самом деле читабельным и красивым:

Такой граф даст хороший обзор, однако часто нужно копать немного глубже. Например, посмотреть историю (эволюцию) определённых файлов или даже отдельных функций; в этом поможет git log с флагом -L::).

Теперь, когда мы немного представляем происходящее в репозитории, мы, возможно, захотим проверить различия между обновлёнными файлами и последним коммитом. Здесь можно воспользоваться git diff; опять же ничего нового здесь нет, но у diff есть кое-какие опции и флаги, о которых вы, возможно, не знаете. Например, можно сравнить две ветки: git diff branch -a branch -b, или даже конкретные файлы в разных ветках: `git diff <commit-a> <commit-b> -- <пути>`.

Иногда чтение git diff становится трудной задачей. Можно попробовать прописать игнорирующий все пробельные символы (white-space) флаг -w, и этим немного заспамить diff, или флаг --word-diff и работать вместо строк с раскрашенными словами.

Если простой статичный вывод в оболочке вас не устраивает, можно запустить difftool, вот так: git difftool=vimdiff, команда откроет файлы diff внутри vim в два окна слева и справа. Очевидно, что Vim не единственный вариант; можно запустить git difftool --tool-help, чтобы увидеть список всех инструментов, которые можно использовать вместе с diff.

Мы уже видели, как просматривать историю конкретных частей или строк в файла с помощью git log. Было бы удобно делать нечто подобное, например, стейджинг частей файлов, правда? И такое легко делается в в IDE, например, в IntelliJ; то же самое уже сложнее в git CLI, но, конечно же, по-прежнему возможно: в git add пропишите опцию --patch:

Команда открывает редактор, в котором отображается один "hunk" [кусок], представляющий собой кусок кода с несколькими отличающимися друг от друга строками в нём. Можно много чего сделать с этим куском, но самые важные опции это y принять изменения (делает стейджинг), n не принимать (не делать стейджинг) и e отредактировать кусок перед стейджингом (полный список опций здесь).

Когда закончите с интерактивным стейджингом, вы можете запустить git status, и увидите, что файл с частичным стейджингом находится в разделах "Changes to be committed:" и "Changes not staged for commit:". Кроме того, можно запустить git add -i (интерактивный стейджинг), а затем воспользоваться командой s (статус), которая покажет вам, какие строки находятся на стейджинге, а какие нет.

Исправление распространённых ошибок

Закончив со стейджингом, я (слишком) часто осознаю, что добавил то, чего добавлять не хотел. Однако на этот случай у git для файлов нет команды un-stage. Чтобы обойти ограничение, можно сбросить репозиторий командой git reset --soft HEAD somefile.txt. Вы также можете включить в git reset флаг -p, который покажет вам тот же UI, что и у git-add -p. Также не забудьте добавить туда флаг --soft, иначе вы сотрёте ваши локальные изменения!

Поменьше грубой силы

Теперь, когда мы закончили стейджинг, всё, что осталось, commit и push. Но что, если мы забыли что-то добавить или совершили ошибку и хотим исправить уже запушенные коммиты? Есть простое решение, использующее git commit -a и git push --force, но оно может быть довольно опасным, если мы работаем над общей веткой, например, master. Таким образом, чтобы избежать риска перезаписи чужой работы из-за того, что мы решили проблему грубой силой, мы можем воспользоваться флагом --force-with-lease. Этот флаг в отличие от --force запушит на изменения только в том случае, если за время работы никто не добавил никаких изменений в ветку. Если ветка была изменялась, код не будет отправлен, и этот факт сам по себе указывает на то, что перед отправкой кода мы должны выполнить git pull.

Правильное слияние веток

Если вы работаете над репозиторием, в котором участвует более одного разработчика, можно с уверенностью предположить, что вы работаете в отдельной ветке, а не в мастере. Это также означает, что рано или поздно вам придётся включить свой код в кодовую базу (главную ветку). Вполне вероятно, что, пока вы работали над своей веткой, кто-то другой уже добавил свой код в мастер, из-за чего ветка вашей функциональности отстаёт на несколько коммитов. Можно пойти напролом и выполнить слияние вашего кода в мастер с помощью git merge, но команда создаст дополнительный комммит слияния, а также, без необходимости на то, затруднит чтение истории и сделает её сложнее:

Подход гораздо лучше (не стесняйтесь спорить со мной по этому поводу, образно говоря, это та высота, на которой я готов умереть) заключается в том, чтобы сделать rebase ветки функции в master, а затем выполнить так называемую быструю перемотку (git merge --ff). Подход сохраняет историю линейной, читать такую историю легче, упрощается и последующий поиск коммитов с новым функционалом и коммитов виновников ошибок.

Но как нам сделать такой rebase? Можно выполнить rebase в его базовой форме с помощью git rebase master feature_branch, чего часто бывает достаточно (за этим следует push --force). Однако, чтобы получить от git rebase максимальную отдачу, также следует включить флаг -i, чтобы rebase был интерактивным. Интерактивный rebase удобный инструмент, чтобы, например, переформулировать, сжать или вообще очистить ваши коммиты и всю ветку. В качестве небольшой демонстрации мы можем даже сделать rebase ветки на саму себя:

Приём выше позволяет нам повторно применять последние 4 коммита и изменить их, получив полезный результат, например сжать одни коммиты и переформулировать другие:

Выше показан пример сеанса rebase. В верхней части показывается ветка перед перезагрузкой. Вторая часть фрагмента это список коммитов, представленных после запуска git rebase каждый из них можно выбрать, чтобы включить в работу (pick). Мы можем изменить действие для каждого из них, а также полностью переупорядочить коммиты. Как показано в третьем разделе примера, некоторые допустимые действия переформулирование (оно говорит git открыть редактор сообщений о коммите), сжатие коммита (объединяет коммиты в предыдущий) и исправление коммита: (исправление работает как сжатие, но при этом сбрасывает сообщение о коммите). После того как мы применим эти изменения и переформулируем изменённые коммиты, мы получим историю, которая показана на скриншоте выше, в его нижней части.

Если во время rebase вы столкнулись с каким-либо конфликтом, чтобы разрешить его, вы можете запустить git mergetool --tool=vimdiff, а затем продолжить rebase с помощью git rebase --continue. git mergetool может быть вам не знаком, на первый взгляд он может показаться пугающим. В действительности же это то же самое, что IDE вроде IntelliJ, просто в стиле Vim. Если вы не знаете хотя бы несколько сочетаний клавиш Vim, то, как и в случае с любым другим использующим этот редактор инструментом, вам, может быть, трудно даже понять, на что на самом деле вы смотрите. Если вам нужна помощь, я рекомендую прочитать эту исчерпывающую статью.

Если всё это кажется слишком сложным или вы просто боитесь работать с rebase, в качестве альтернативы создайте пул реквест на GitHub и нажмите кнопку Rebase and merge, чтобы сделать, по крайней мере, простые и быстрые rebase и merge с быстрой перемоткой.

Главное эффективность

Я думаю, что примеры выше показали несколько изящных советов и хитростей, но всё это может быть довольно сложно запомнить, особенно когда дело касается команд вроде git log. К счастью, чтобы разрешить эти трудности, можно воспользоваться глобальной конфигурацией git. Она находится в ~/.gitconfig и обновляется каждый раз, когда вы запускаете git config --global. Даже если вы не настраивали этот файл, он, вероятно, содержит кое-какие базовые вещи, такие как раздел [user], но можно добавить много других разделов:

Выше приведён пример некоторых из доступных опций конфигурации. Примечательно, что длинная команда git log это только псевдоним git graph. Автокоррекция установлена 10: такое значение включает её и заставляет ждать 1 секунду, прежде чем выполнить правильную команду, в которой была опечатка, и, наконец, последний раздел подписывание коммита GPG (подробнее об этом читайте ниже).

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

• https://github.com/jessfraz/dotfiles/blob/master/.gitconfig

• https://gist.github.com/pksunkara/988716

• https://github.com/mgedmin/dotfiles/blob/master/gitconfig

Автозавершение команд это инструмент не менее продуктивный, чем псевдонимы, и он просто устанавливается:

Extras

Можно не только писать свои псевдонимы, но и взять на вооружение плагин git-extras, он вводит много полезных команд, которые могут немного упростить вам жизнь. Я не буду вдаваться в подробности обо всех возможностях этого плагина посмотрите список команд, а я просто покажу один краткий пример из этого списка прямо здесь:

• git delta список файлов, которые в другой ветке отличаются.

• git show-tree древовидное представление коммитов всех ветвей, похожее на показанный ранее git log.

• git pull-request пул-реквест в командной строке.

• git changelog генерирует журнал изменений (changelog) из тегов и сообщений в коммитах.

Конечно, это не единственный крутой плагин. Например, есть ещё один удобный инструмент, позволяющий открыть репозиторий в браузере прямо из командной строки. Кроме того, в приглашении терминала можно настроить статус репозитория, это делается с помощью zsh или bash-it.

Подписываем коммиты

Даже если вы никогда не вкладывались в какой-либо проект Open Source, вы, вероятно, прокручивали историю коммитов такого проекта. В ней вы, скорее всего, видели значок подтверждённого (sign-off знак о правах на ПО), проверенного или подписанного коммита. Что это такое и зачем?

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

Сверху видно, что в git commit с опцией --sign-off в конце сообщения о коммите автоматически добавляется строка Signed-off-by: , которая формируется на основе вашего имени пользователя в конфигурации git.

Что касается значка signed/verified, который вы, вероятно, заметили в некоторых репозиториях, он существует, потому что на GitHub довольно легко выдавать себя за других пользователей. Всё, что вам нужно сделать, изменить имя сделавшего коммит человека и электронную почту в вашей конфигурации и отправить изменения. Чтобы предупредить ситуацию, вы можете подписывать коммиты с помощью ключей GPG, подтверждающих, что автор коммита и отправитель изменений на самом деле является тем, за кого он себя выдаёт. Подпись коммита более распространена, чем подтверждение прав, поскольку важно знать, кто на самом деле внёс код.

Если вы хотите начать пользоваться этой функцией или, возможно, хотите внедрить её в вашей команде, можно сделать следующее:

Сначала вы генерируете пару ключей GPG (если у вас её ещё нет), затем устанавливаете ключи при помощи git config и, наконец, добавляете опцию -S, когда делаете коммит. Затем, посмотрев на информацию о коммите на GitHub, вы увидите значок, как на картинке ниже.

Однако, как видно на изображении, подпись не проверена, потому что GitHub не знает, что ключ GPG принадлежит вам. Чтобы это исправить, открытый ключ из нашей пары ключей нужно отправить на GitHub. Для этого экспортируем ключ командой gpg --export, как здесь:

Затем скопируйте этот ключ и вставите его в поле https://github.com/settings/gpg/new. Если вы проверите ранее подписанный коммит после добавления ключа, то увидите, что коммит теперь проверен (verified). Здесь предполагаем, что вы добавили на GitHub именно тот ключ, которым подписывали коммит:

Заключение

Git очень мощный инструмент, у которого слишком много подкоманд и опций, чтобы в одной статье описать их все. Если вы хотите глубже погрузиться в некоторые связанные с Git темы, я бы порекомендовал прочитать Debugging with Git, чтобы узнать больше о blame, bisect или Getting solid at Git rebase vs. merge, чтобы глубже понять rebase и merge. Помимо множества полезных статей в Интернете часто при поиске информации о некоторых тонкостях git лучший выбор это мануал, который выводится опцией --help, или версия в сети.

Узнайте подробности, как получить Level Up по навыкам и зарплате или востребованную профессию с нуля, пройдя онлайн-курсы SkillFactory со скидкой 40% и промокодомHABR, который даст еще +10% скидки на обучение.

• Профессия Data Scientist

• Профессия Data Analyst

• Курс по Data Engineering

Всем привет.

Есть такие люди, которые работают с облачной инфраструктурой и не используют автоматизацию, потому что это долго, нужно вникать, а им надо фичи пилить. Накликали что-то там в UI, подключились по ssh, поставили всякого с помощью apt и т.д. и конфигурационные файлы ещё вручную поменяли. Документации конечно же написать времени не хватило или в ней много разных хитрых шагов и повторить настройку этой инфраструктуры в точности уже нельзя или очень сложно, а сервисы крутятся в проде. А потом человек забыл что и как делал в точности или вообще уволился.

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

К слову, крайне рекомендую для автоматизации много чего, но в особенности облачных провайдеров вроде AWS / GCP / Azure и т.д. использовать именно Terraform, т.к. это достаточно зрелый инструмент, у него большое сообщество и кроме всего прочего он поддерживает автоматизацию далеко не только каких-то облачных провайдеров, но и практически всего у чего есть API. К тому же инструмент open source и при желании можно реализовать что угодно самостоятельно. Для таких облаков, как AWS не рекомендую пытаться реализовывать автоматизации с помощью чистого питона и запросов к AWS API с помощью cli или Cloudformation.

Также у Terraform есть удобная возможность организовывать код в блоки называемые модулями и передавая в них только параметры легко создавать необходимое с другими настройками.

Для тех, кто совсем не знаком с Terraform упомяну, что если в одну папку положить несколько файлов с расширением .tf и запустить Terraform в этой папке, то Terraform прочитает и использует код из всех файлов, а не только одного. Это в том числе позволяет разбивать один большой main.tf файл с кучей ресурсов на какие-то удобные вам логические блоки.

Итак, например, встала задача развернуть vpn серверы WireGuard на базе Ubuntu 20.04 в нескольких регионах + немного мониторинга. Поддержка WireGuard сейчас есть в ядре linux, но дополнительные инструменты, которые можно поставить отдельно облегчают жизнь, поэтому поставим и их.

Весь код модуля выложен здесь.

Также этот модуль опубликован в реестре модулей здесь.

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

Итак, создаются необходимые для работы iam политики, роль и т.п.

Используем elastic ip, отдельный для сервера в каждом регионе, которые нужно прописать в dns для того, чтобы пользователь мог использовать единое имя для подключения к vpn серверу. Планировал использовать geo dns route53, чтобы при местоположении пользователя в оперделённом регионе ему бы отдавался ip vpn сервера в его регионе, но т.к. на этом проекте route53 пока не используется, то создание записей в нём пока не автоматизировал.

Создаются security groups с правилами, которые позволяют подключиться к vpn серверу извне по udp (Wireguard работает только по udp) + ssh + несколько портов для prometheus exporter'ов.

Создаётся собственно сервер / ec2 машина, но не просто отдельно стоящая, а входящая в auto scaling group, в данном примере в единственном варианте. Это сделано для того, чтобы если с сервером что-то не так, то Амазон автоматом пересоздаст его. Self healing.

Позже немного допилив конфигурацию и добавив в неё load balancer можно добиться того, для чего auto scaling groups отлично подходят: при повышенной нагрузке на какой-то из ресурсов сервера, например на cpu, можно реализовать автоматическое создание дополнительных vpn серверов, а соответственно при падении нагрузки уменьшать их количество.

Этот модуль можно использовать просто с Terraform, но лучше использовать Terragrunt, который позволяет делать некоторые удобные вещи и местами реализовывать концепцию Keep your Terraform code DRY, например параметризуя некоторые вещи в backend блоке, чего сам Terraform пока не умеет. Terraform хранит состояние инфраструктуры в специальном файле и принято хранить его не локально, а, чаще всего, в S3 бакете. Также, если вы работаете с этим кодом не в одиночку, то принято хранить локи в Dynamodb, чтобы случайно не применить какое-то изменение инфраструктуры несогласованно и не поломать всё.

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

С помощью файла terragrunt.hcl в корне репозитория (https://github.com/vainkop/terraform-aws-wireguard/blob/master/example/terragrunt.hcl) я могу, например, задать место для хранения state для всех поддиректорий, а потом ссылаться на этот файл в других terragrunt.hcl с помощью функции find_in_parent_folders() https://github.com/vainkop/terraform-aws-wireguard/blob/master/example/us-east-1/terragrunt.hcl#L2

При этом key, т.е. файл, где будет храниться состояние инфраструктуры в конкретном регионе будет храниться отдельно, что достигается с помощью функции path_relative_to_include() https://github.com/vainkop/terraform-aws-wireguard/blob/master/example/terragrunt.hcl#L11

Также я реализовал хранение/чтение переменных в yaml формате, что мне кажется более удобочитаемым с помощью функции yamldecode(file(...)) https://github.com/vainkop/terraform-aws-wireguard/blob/master/example/eu-central-1/terragrunt.hcl#L9

Вот так выглядит пример передаваемых в модуль уникальных параметров (конечно YOUR_... нужно заменить на реальные значения): https://github.com/vainkop/terraform-aws-wireguard/blob/master/example/us-east-1/values.yaml

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

В итоге в вашем приватном репозитории код из которого применяете либо вы, либо какой-то ci cd runner может лежать только содержимое похожее на мою папку example, т.е. только terragrunt.hcl и yaml файлы с параметрами, а модуль можно использовать как публичный и хорошо поддерживаемый, так и написать свой. Это позволяет отдать "пользователям" только задание параметров в yaml и в принципе ничего не знать про Terraform код.

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

Для того, чтобы изменения в коде open source модулей, как впрочем и в частных, не повлияли на работу вашей автоматизации принято фиксировать версии используемых модулей, например в моём коде это сделано с помощью source = "github.com/vainkop/terraform-aws-wireguard?ref=v1.2.0" здесь https://github.com/vainkop/terraform-aws-wireguard/blob/master/example/eu-central-1/terragrunt.hcl#L6

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

Например я реализовал cloud-init скрипт, который осуществляет предварительную установку и настройку софта на свежеразвёрнутый сервер и делает это каждый раз, когда сервер пересоздаётся в auto scaling group, что очень удобно: https://github.com/vainkop/terraform-aws-wireguard/blob/master/templates/user-data.txt

Ближе к концу скрипта устанавливается 2 prometheus exporter'а, которые позволяют как мониторить метрики самой ec2 машины, так и базовые метрики самого WireGuard, на основании которых можно построить удобные Dashboards и соответственно определённые alerts и т.п.

В частности я реализовал это для того, чтобы видеть к какому из vpn серверов подключён клиент, чтобы, например, была возможность подключиться к нему именно из его региона, т.к. связности между этими vpn серверами нет. Т.к. клиентские публичные ключи зашиты в каждый из серверов и серверные ключи одинаковые, то клиент будет автоматически переключаться между ними путешествуя между регионами на основании geo ip route53.

Также привожу пример кода из .gitlab-ci.yml и Dockerfile где можно увидеть какие команды используются для применения всего этого хозяйства с помощью Gitlab runner'а и какой docker контейнер можно использовать для этого runner'а.

$ cat .gitlab-ci.ymlstages:  - build  - plan  - apply  - destroyvariables:  GIT_DEPTH: 1.aws_configure: &aws_configure  before_script:    - aws configure set aws_access_key_id $AWS_ACCESS_KEY_ID    - aws configure set aws_secret_access_key $AWS_SECRET_ACCESS_KEY    - aws configure set default.region $AWS_DEFAULT_REGIONbuild-terraform:  image: docker:19.03.15  services:    - docker:19.03.15-dind  stage: build  variables:    DOCKER_TLS_CERTDIR: ""    DOCKER_HOST: tcp://docker:2375    DOCKER_DRIVER: overlay2    TERRAFORM_VERSION: "0.13.6"    TERRAGRUNT_VERSION: "v0.28.9"  before_script:    - printenv    - docker info    - echo $CI_REGISTRY_PASSWORD | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin  script:    - cd docker    - docker build --build-arg TERRAFORM_VERSION=$TERRAFORM_VERSION --build-arg TERRAGRUNT_VERSION=$TERRAGRUNT_VERSION -t $CI_REGISTRY_IMAGE:$TERRAFORM_VERSION .    - docker push $CI_REGISTRY_IMAGE:$TERRAFORM_VERSION  rules:    - changes:        - docker/*plan-us-east-1:  image:    name: registry.gitlab.com/vainkop/terraform:0.13.6    entrypoint: [""]  stage: plan  <<: *aws_configure  script:    - cd wireguard/us-east-1    - terragrunt run-all plan --terragrunt-non-interactive -out $CI_PROJECT_DIR/wireguard/us-east-1/tfplan-$CI_COMMIT_SHA  artifacts:    paths:    - $CI_PROJECT_DIR/wireguard/us-east-1/tfplan-$CI_COMMIT_SHA    expire_in: 1 month  rules:    - changes:        - wireguard/us-east-1/*      allow_failure: trueplan-eu-central-1:  image:    name: registry.gitlab.com/vainkop/terraform:0.13.6    entrypoint: [""]  stage: plan  <<: *aws_configure  script:    - cd wireguard/eu-central-1    - terragrunt run-all plan --terragrunt-non-interactive -out $CI_PROJECT_DIR/wireguard/eu-central-1/tfplan-$CI_COMMIT_SHA  artifacts:    paths:    - $CI_PROJECT_DIR/wireguard/eu-central-1/tfplan-$CI_COMMIT_SHA    expire_in: 1 month  rules:    - changes:        - wireguard/eu-central-1/*      allow_failure: trueapply-us-east-1:  image:    name: registry.gitlab.com/vainkop/terraform:0.13.6    entrypoint: [""]  stage: apply  <<: *aws_configure  script:    - cd wireguard/us-east-1    - terragrunt run-all apply --terragrunt-non-interactive -auto-approve $CI_PROJECT_DIR/wireguard/us-east-1/tfplan-$CI_COMMIT_SHA  rules:    - changes:        - wireguard/us-east-1/*      when: manual      allow_failure: trueapply-eu-central-1:  image:    name: registry.gitlab.com/vainkop/terraform:0.13.6    entrypoint: [""]  stage: apply  <<: *aws_configure  script:    - cd wireguard/eu-central-1    - terragrunt run-all apply --terragrunt-non-interactive -auto-approve $CI_PROJECT_DIR/wireguard/eu-central-1/tfplan-$CI_COMMIT_SHA  rules:    - changes:        - wireguard/eu-central-1/*      when: manual      allow_failure: truedestroy-us-east-1:  image:    name: registry.gitlab.com/vainkop/terraform:0.13.6    entrypoint: [""]  stage: destroy  <<: *aws_configure  script:    - cd wireguard/us-east-1    - terragrunt run-all destroy --terragrunt-non-interactive -auto-approve  rules:    - changes:        - wireguard/us-east-1/*      when: manual      allow_failure: truedestroy-eu-central-1:  image:    name: registry.gitlab.com/vainkop/terraform:0.13.6    entrypoint: [""]  stage: destroy  <<: *aws_configure  script:    - cd wireguard/eu-central-1    - terragrunt run-all destroy --terragrunt-non-interactive -auto-approve  rules:    - changes:        - wireguard/eu-central-1/*      when: manual      allow_failure: true

$ cat docker/DockerfileFROM ubuntu:20.04USER rootARG DEBIAN_FRONTEND=noninteractiveARG TERRAFORM_VERSIONENV TERRAFORM_VERSION=$TERRAFORM_VERSIONARG TERRAGRUNT_VERSIONENV TERRAGRUNT_VERSION=$TERRAGRUNT_VERSIONRUN set -x && \    apt-get update && \    apt-get install -y \    apt-transport-https \    ca-certificates \    build-essential \    software-properties-common \    unzip \    net-tools \    wget \    curl \    python3 \    python3-dev \    python3-pip \    jq \    gettext-base \    git && \    rm -rf /var/lib/apt/lists/*RUN set -x && \    apt-key adv --keyserver keyserver.ubuntu.com --recv-keys CC86BB64 && \    add-apt-repository ppa:rmescandon/yq && \    apt update && \    apt install -y yq && \    rm -rf /var/lib/apt/lists/*RUN set -x && \    pip3 install -U --no-cache-dir setuptools shyamlRUN set -x && \    ln -sf /usr/bin/python3 /usr/bin/python && ln -sf /usr/bin/pip3 /usr/bin/pipRUN set -x && \    curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" && \    unzip awscliv2.zip && \    rm awscliv2.zip && \    ./aws/installRUN set -x && \    cd /tmp && \    curl -O https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_amd64.zip && \    unzip terraform_${TERRAFORM_VERSION}_linux_amd64.zip -d /usr/local/bin && \    chmod +x /usr/local/bin/terraform && \    rm /tmp/terraform_${TERRAFORM_VERSION}_linux_amd64.zipRUN set -x && \    wget "https://github.com/gruntwork-io/terragrunt/releases/download/${TERRAGRUNT_VERSION}/terragrunt_linux_amd64" && \    mv terragrunt_linux_amd64 /usr/local/bin/terragrunt && \    chmod +x /usr/local/bin/terragruntRUN set -x && \    curl --version && \    envsubst --version && \    python --version && \    pip --version && \    shyaml --version && \    jq -V && \    yq -V && \    aws --version && \    terraform --version && \    terragrunt --versionENTRYPOINT ["/bin/bash", "-c"]

За код не ругайте, написал за несколько часов и решил поделиться.

Если есть конкретные замечания/предложения, то готов их выслушать либо в комментариях, либо в личке, например, в телеграм: @vainkop

Прошу также учитывать, что это моя первая публикация на Хабре. Приглашение приму с удовольствием.

Всем привет.

Дисклеймер: сказу скажу, что пишу статью по-ходу дела, "код" в ней рабочий, но не претендует на какие-либо best practices, поэтому не придирайтесь :) Цель статьи: донести до интересующейся русскоязычной части населения общие принципы, возможно разбудить интерес поразбираться самостоятельно и сделать что-то гораздо лучше и интереснее. Итак поехали!

Допустим Вы работаете с Terraform / Terragrunt (второе здесь непринципиально, но лучше изучайте, если ещё не используете) и автоматизируете инфраструктуру, например, в AWS (но совершенно необязательно AWS). Инфраструктура в коде репозитория, разворачивается из него же, казалось бы вот оно GitOps счастье :)

Всё идёт хорошо, пока какой-то пользователь не поменял что-то руками через консоль / UI и конечно забыл об этом кому-либо сказать. А то и сделал что-то нехорошее намеренно. И вот он ваш дрейф: код и инфраструктура больше не совпадают! :(

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

Как обычно, есть много различных путей добиться желаемого. Например, недавно на горизонте появилась неплохо развивающаяся утилита https://github.com/cloudskiff/driftctl , которая может даже больше, чем предложу Вашему вниманию чуть ниже я, но на момент написания статьи driftctl как минимум не поддерживает работу с aws provider v2, а также не умеет в multi region, что делает его использование невозможным в большинстве серьёзных проектов. Но ребята обещают доделать её через месяц-два.

А пока что опишу и приведу пример небольшого количества кода для следующей очень простой схемы:

1) создаём pipeline, который или по расписанию (в Gitlab можно воспользоваться Pipeline schedules) или по кругу будет делать terraform plan

2) при нахождении дрейфа (diff в плане) pipeline будет, например, отправлять сообщение с его содержанием в Slack.

Аналогично можно реализовать и, например, создание issue в любом из используемых вами репозиториев, где поддерживается их создание через api и любое другое действие, например apply, который вернёт инфраструктуру к её эталонному состоянию. Или всё-таки импортировать изменение в state, если оно действительно необходимо.

Допустим есть репозиторий содержащий код для вашей live инфраструктуры, т.е. код, которому она должна соответствовать и откуда она и была развёрнута с такой структурой:

account_1/ eu-central-1  dev   eks    terragrunt.hcl    values.yaml   s3-bucket       terragrunt.hcl       values.yaml  prod   eks    terragrunt.hcl    values.yaml   s3-bucket       terragrunt.hcl       values.yaml  staging      eks       terragrunt.hcl       values.yaml      s3-bucket          terragrunt.hcl          values.yaml us-east-1  dev   eks    terragrunt.hcl    values.yaml   s3-bucket       terragrunt.hcl       values.yaml  prod   eks    terragrunt.hcl    values.yaml   s3-bucket       terragrunt.hcl       values.yaml  staging      eks       terragrunt.hcl       values.yaml      s3-bucket          terragrunt.hcl          values.yaml terragrunt.hcl

В приведённом выше примере в папке account_1 находятся 2 папки: us-east-1 и eu-central-1 , по имени регионов AWS. Иногда удобно организовать структуру именно так и тогда имена папок можно использовать как значение для передачи в модуль с помощью Terragrunt функции/й, например, таких "${basename(get_terragrunt_dir())}"

Аналогичная логика с папками имеющими в названии окружение и далее идут названия самих компонентов, которых в этом примере 2: eks и s3-bucket

Если смотреть от корня репозитория, то путь до каждого из файлов внутри папки компонента

<account_name>/<region>/<environment>/<component>/*

Т.е. "в общих чертах" */*/*/<component>/*

Выберем, например, компонент s3-bucket (на самом деле конечно можно реализовать это для всего сразу, но бывают нюансы и здесь интересно показать принцип).

Не забудьте подключить Incoming WebHooks в Slack и записать полученный Webhook URL. Делается это так: https://api.slack.com/messaging/webhooks

Тогда вот такой скрипт может выполнять требуемое планирование в pipeline и отправку в Slack diff'а при его нахождении:

#!/bin/bashROOT_DIR=$(pwd)plan () {  echo -e "$(date +'%H-%M-%S %d-%m-%Y') $F"  CURRENT_DIR=$(pwd)  PLAN=$CURRENT_DIR/plan.tfplan  terragrunt run-all plan --terragrunt-non-interactive -lock=false -detailed-exitcode -out=$PLAN 2>/dev/null || ec=$?    case $ec in    0) echo "No Changes Found"; exit 0;;    1) printf '%s\n' "Command exited with non-zero"; exit 1;;    2) echo "Changes Found! Reporting!";          MESSAGE=$(terragrunt show -no-color ${PLAN} | sed "s/\"/'/g");    # let's replace the double quotes from the diff with single as double quotes "break" the payload       curl -X POST --data-urlencode "payload={\"channel\": \"#your-slack-channel-here\", \"username\": \"webhookbot\", \"text\": \"DRIFT DETECTED!!!\n ${MESSAGE}\", \"icon_emoji\": \":ghost:\"}" https://hooks.slack.com/services/YOUR/WEBHOOK/URL_HERE;;  esac}N="$(($(grep -c ^processor /proc/cpuinfo)*4))"    # any number suitable for your situation goes herefor F in */*/*/s3-bucket/*; do  ((i=i%N)); ((i++==0)) && wait    # let's run only N jobs in parallel to speed up the process  cd $ROOT_DIR  cd $F  plan &    # send the job to background to start the new onedone

Меняем что-нибудь руками, запускаем pipeline или ждём его выполнения и радуемся :)

На этом на сегодня всё!

Если Вы решали подобную задачу иначе, есть конкретные замечания/предложения, или просто хочется что-то спросить, то, по мере возможности, готов выслушать либо в комментариях, либо в личке, например, в телеграм @vainkop

P.S. имхо проект https://github.com/cloudskiff/driftctl мне лично кажется действительно полезным и решающим правильную задачу и хороших аналогов ему нет, так что прошу поддержать ребят, а по-возможности внести свою лепту ибо open source.

Всем хорошего настроения!

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

Выпускнику и преподавателю Computer Science Center, Равилю Галееву, пришла идея собрать такие инструменты и технологии в один курс и познакомить студентов с ними. За пример такого курса были взяты The Missing Semester of Your CS Education от MIT, Software Carpentry и cs50.

В этом посте мы собрали видеолекции курса Практический минимум и материалы к занятиям. Благодарим Равиля за подборку!

Содержание

Введение в Linux

Командная строка Linux

Система контроля версий git

Языки разметки и XML

Регулярные выражения

Взаимодействие с сетью

Протокол HTTP

Контейнеризация

Архитектура приложений

Тестирование приложений

Опасность в приложениях

Билд-системы

Кодировки, даты, локали

Дебаг

Набор в Computer Science Center 2021

Введение в Linux

• Буквально пара слов о том, что такое ядро

• Набор исторических фактов (от Unix к Linux)

• Файловая система

• Пользователи

• Файлы

• Процессы

• Unix way

Слайды

Статьи

Wikipedia History of Unix

Книги

• Brian Kernighan and Rob Pike - The Unix Programming Environment

• Peter Seibel - Coders at Work: Reflections on the Craft of Programming

• Steve Parker - Shell Scripting: Expert Recipes for Linux, Bash, and More

• David Griffiths and Dawn Griffiths - Head First C

Видео

• Александр Смаль История Unix систем

• Александр Смаль Пользователи, файлы и процессы

Курсы

• UNИX ПО GNU/Linux

• Stepik Основы программирования для Linux

• Stepik Введение в Linux

Командная строка Linux

• bash как REPL

• Unix way

• Шебанг

• make

Слайды

Статьи

• Bash scripting cheatsheet

• Chaining commands (Part 2: Redirections and pipes)

• The first web page, viewed by the first web browser, on a teletype, retrocomputing completeness

• Software carpentry make

Книги

Ian Miell Learn Bash the Hard Way

Видео

• Александр Смаль Bash скрипты

• Виктор Ашик 008. Командная строка Unix

• Виктор Ашик 004. Командная строка Unix

• Brian Will Unix terminals and shells part1 part2 part3 part4 part5

• Евгений Линский Основы C++. Лекция 2

• Using a TTY Model 43 as a console on Linux

Слайды/Презентации

• Adrien Mahieux Bash for production systems

Bash-скрипты из реального мира

• brew

• sentry

• git

• ignite

Система контроля версий git

• git

  • commit

  • branch

  • merge

• git flow

• github

Слайды

Статьи

• Евгений Артюхов Ежедневная работа с Git

• Vincent Driessen A successful Git branching model

• Chris Beams How to Write a Git Commit Message

• Atlassian Git Tutorials

• ohshitgit

Книги

• Scott Chacon and Ben Straub Pro Git

Видео

• Learn to Git: Basic Concepts

• Git & GitHub: Merge Strategies

• Марат Мавлютов 002. Системы контроля версий

• Марат Мавлютов 003. Системы контроля версий

• Глеб GIT для Дата Саентиста

• missing semester mit Lecture 6: Version Control (git)

Потренироваться

• learngitbranching

• visualizing-git

• try.github.io

• Julia Evans git exercises: navigate a repository

Языки разметки и XML

• groff

• LaTex

• XML, JSON, YAML

• Markdown, AsciiDoc

• GraphViz, PlantUML

Слайды

Статьи

• Дмитрий Переверза Зачем нам UML

• Поташников Николай PlantUMLвсе, что нужно бизнес-аналитику для создания диаграмм в программной документации

• Иван Пономарев Презентация как код

• Иван Кочуркин Современный формат презентаций

• Амет Умеров Как я диплом в LaTeX писал с GitHub, Docker и TravisCI

• John Gruber Markdown

• Matt Welsh Writing man Pages Using groff

• Eddie Smith From boiling lead and black art: An essay on the history of mathematical typography

Книги

К. В. Воронцов LATEX в примерах

Видео

• Александр Смаль LaTeX

• Владислав Танков Terraforming Clouds Видео

• Tony Ibbs A brief history of text markup languages Видео Слайды

• Самарев Роман Языки веб-программирования. SGML, HTML, CSS | Технострим

Слайды и другие материалы

• Tony Ibbs A brief history of text markup languages

• Борис Демешев latex_examples

Markdown cheatsheets

• Boostnote

• Github

• Stackoverflow

Разное

• kroki.io

• ditaa

• draw.io

• boostnote app

• Cartman в SVG

• detexify

• graphviz

• GraphvizOnline

• texample

• plantUML

• PlantUML Web Server

• mermaidJS

• websequencediagrams

• Asciidoctor

• Database schema to a graphical entity-relationship diagram

• gnuplot

Регулярные выражения

• Регулярки

• grep

• sed

• awk

Слайды

Статьи

• Кроссворд из регулярных выражений

• Quantifiers (The Java Tutorials > Essential Classes > Regular Expressions)

• Регулярные выражения изнутри / Хабр

• Шахматы на чистом sed / Хабр

• Bash-скрипты, часть 7: sed и обработка текстов / Блог компании RUVDS.com / Хабр

Видео

• Corey Schafer Regex Tutorial

• Александр Смаль Регулярные выражения

• Oliver Wegner sed basics

• Михайло Иванкив Как я однажды верстал форму регистрации

Слайды и другие материалы

• RegExr: Learn, Build, & Test RegEx

• Debuggex: Online visual regex tester. JavaScript, Python, and PCRE.

• regex - Greedy vs. Reluctant vs. Possessive Quantifiers - Stack Overflow

• poormansprofiler.org

• Regular Expression Reference: Special Groups

Взаимодействие с сетью

• Разбираемся как работает посылка пакетов

• Рассматриваем простейшие утилиты работы с сетью

• Знакомимся с DNS, CDN, VPN и другими словами на три буквы

• Пишем сервер на сокетах

Слайды

Материалы

• Julia Evans Networking!

• 4. HIGHLOAD. Сетевой стек | Технострим

• Beej's Guide to Network Programming

• Tim Urban

Протокол HTTP

• HTTP

• REST

Слайды

Статьи

• HTTP/2

• CORS

• Zalando RESTful API and Event Scheme Guidelines

• MDN Web Docs

• Networking tool comics! - Julia Evans

• SIP URI и URL. Часть 1 (URI, URL и URN) / Хабр

• Давайте уже разберемся в DNS / Хабр

• 15 тривиальных фактов о правильной работе с протоколом HTTP / Блог компании Яндекс / Хабр

• Практические советы, примеры и туннели SSH / Хабр

• WebSockets полноценный асинхронный веб / Хабр

• Что же такое этот GraphQL? / Хабр

Видео

• HTTP: History & Performance - Ana Balica

• HTTP/3 - HTTP over QUIC is the next generation by Daniel Stenberg

• A Beginner's Guide to WebSockets

• HTTP/2 101

Разное

• curl exercises - Julia Evans

• dionmisic/ajax

• dionmisic/ws

• htt2 демка

• graphiql-online

Контейнеризация

• chroot

• Docker

• Docker compose

Слайды

Статьи

• hexlet docker

• How to Run Multiple Linux Distros Without Virtualization - Make Tech Easier

• A Basic Chroot Example in Ubuntu

• Docker Documentation

• Docker - XennisWiki

• docker Archives - Dots and Brackets

• docker - What is the difference between CMD and ENTRYPOINT in a Dockerfile? - Stack Overflow

Видео

• Solomon Hykes Introduction to Docker

• Jake Wright Docker Compose in 12 Minutes Learn Docker in 12 Minutes

• Mumshad Mannambeth Kubernetes for the Absolute Beginners

Курсы

• Управление вычислениями Stepik

• Get Started,Docker Documentation

• A Docker Tutorial for Beginners

• Katacoda - Interactive Learning Platform for Software Engineers

Разное

• Create a base image | Docker Documentation

• chroot jails on OS X // galvanist

• Exploring Redis with Docker

• GitHub - skissane/mkjail: Shell script to create a chroot jail on Mac OS X

Архитектура приложений

• ООП

• Паттерны

• Многослойная архитектура

Слайды

Статьи

• AntiPatterns Catalog

• Шаблоны проектирования с человеческим лицом

• ООП в картинках

• Простое объяснение принципов SOLID

• Design Patterns

• Design Patterns & Refactoring

Книги

• head first design patterns

• методология программирования

Курсы

• CSC444F: Software Engineering I

Видео

• Greg Wilson What We Actually Know About Software Development, and Why We Believe Its True

• John Ousterhout A Philosophy of Software Design

• Jonathan Blow Preventing the Collapse of Civilization

• 12 Общие рекомендации по декомпозиции программы

Тестирование приложений

• Тестирование

• Логгирование

Слайды 1

Слайды 2

Статьи

• Why Most Unit Testing is Waste

• Brian Kernighan Code Testing and its Role in Teaching

• The Practical Test Pyramid

• Defining Test Boundaries

• Катастрофические последствия программных ошибок

• Мифы о безопасном ПО: уроки знаменитых катастроф | Открытые системы. СУБД | Издательство Открытые системы

• Logging in Python Real Python

• Tracing microservices with Zipkin and Kibana - merapar - Medium

• Replacing Cassandra's tracing with Zipkin

Видео

• UNИX 08. Тестирование и тестовое покрытие (эфир)

• UNИX 08. Тестирование

• Анатолий Островский Логирование и трассировка запросов. Best Practices

• Антон Бевзюк Демонстрация TDD на Java

• Jakub Nabrdalik Improving your Test Driven Development in 45 minutes

Опасность в приложениях

• Хеширование, контрольные суммы

• Авторизация vs Аутентификация; JWT

• Обмен ключами Диффи-Хеллман

• RSA

• TLS

• Двухфакторная аутентификация

Слайды

Статьи

• Введение в TLS для практиков Патриков

• Encode/Decode text & files to Base64 in Browser with Base64 Converter

• Basic, Bearer, Digest Oh MY! So Many Auths!

• Sunshine's Homepage - Understanding CRC

• Doctrina - How RSA Works With Examples

• Введение в KDF на примере решения криптографического ребуса / Хабр

• Как HTTPS обеспечивает безопасность соединения: что должен знать каждый Web-разработчик / Хабр

• One-Time Passwords from Your Watch | | Circuit Cellar

• Diagrams And Movies Of All The OAuth 2.0 Flows - Takahiko Kawasaki - Medium

• OAuth 2.0 простым и понятным языком / Блог компании Mail.ru Group / Хабр

• How To Safely Store A Password | codahale.com

Видео

• Base64 is not encryption

• Hashing Algorithms and Security

• Hubert Sablonnire 100% Stateless with JWT

• SHA: Secure Hashing Algorithm

• Laurens Van Houtven Crypto 101

• Diffie Hellman Key Exchange by khan academy (смотреть с середины)

• Поздняков С.Н. НОД. Расширенный алгоритм Евклида.

Книги

• С. Рыбин, С. Поздняков Дискретная математика

• М. Бабенко М. Левин Введение в теорию алгоритмов и структур данных

Билд-системы

• от make к TravisCI

• dockerhub

Слайды

Статьи

• Database version control Liquibase versus Flyway - robloxro - Medium

• 5 Blue-Green Deployment Best Practices for a Smooth Release | BlazeMeter

Видео

• Денис Чернилевский Инструменты непрерывной интеграции

• Антон Кекс Что такое Работающий Продукт и как его делать

Разное

Anatomy of a Continuous Integration and Delivery (CICD) Pipeline

Кодировки, даты, локали

Разбираемся, почему /dev/random печатает краказябры

Слайды

Статьи

• Что нужно знать каждому разработчику о кодировках и наборах символов для работы с текстом

• Что нужно знать каждому разработчику о кодировках и наборах символов для работы с текстом, часть 2

• The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets

• How integers are stored in memory using twos complement

• An Implementation of Unicode Normalization - Concerning Pharo - Medium

• What every programmer should know about time | Hacker News

• Что нужно знать про арифметику с плавающей запятой

• Магическая константа 0x5f3759df

• Пара слов о числах с плавающей точкой в Java

• 5 правил работы с суммами

Видео

• Андрей Акиньшин Поговорим про арифметику

• Computerphile Floating Point Numbers

• Tomasz Nurkiewicz Charbuster: 10 mitw o Unicode Слайды

• Tomasz Nurkiewicz Krtka historia czasu Слайды

• Александр Смаль Кодировки

• Adrian Furtuna Practical Exploitation of rounding vulnerabilities in banking applications

• How About UNICODE and UTF-8

• Decimal to IEEE 754 Floating Point Representation

Дебаг

• Исключения

• Дебаг

Слайды

Статьи

• Strace в Linux: история, устройство и использование

• A Crash Course on the Depths of Win32 Structured Exception Handling

• Program and Data Representation: Tutorials

• Using C to inspect Linux syscalls

• Lets Write a Debugger!

• Trapflag-Tracing I: Observing the Execution of a Program from Within Itself

• A zine about strace

• Perl script uses Ptrace for process tracing

• How debuggers work: Part 1 - Basics

• Write yourself an strace in 70 lines of code

• Chrome DevTools

Книги

• Brian Kernighan and Rob Pike - The Practice of Programming

Видео

• Harvard CS50 Introduction to GDB a tutorial

• Harvard CS50 GDB

• Pawe Moll How do debuggers (really) work

• Кирилл Кринкин Отладка в Linux. Краткие сведения о gdb

• Quick Intro to gdb

• Let's write a Debugger!

• Debugging and Profiling

Курсы

Кирилл Кринкин Основы программирования для Linux

Разное

• strace

• GDB to LLDB command map

• GDB kind of doesn't work on macOS Sierra

• GCC -g vs -g3 GDB Flag: What is the Difference?

• ptr_inspect.c

Делитесь в комментариях своими рекомендациями материалов, которые пригодились вам.

Набор в Computer Science Center 2021

Помимо лекций и материалов студентам CS центра на курсе доступны домашние задания. Если вы хотите проходить ещё больше курсов по разным направлениям, приходите поступать.

CS центр это вечерние курсы по математике и программированию. Занятия проходят в Санкт-Петербурге и в Новосибирске. Жители других городов могут поступить на обучение в удалённом формате.

Чтобы поступить:

заполните анкету на сайте до 10 апреля,

решите задания онлайн-теста до 11 апреля,

участвуйте в онлайн-экзамене в конце апреля-начале мая,

пройдите собеседование в мае-июне.

Для тех, кто успешно справится со вступительными испытаниями, занятия начнутся в сентябре. Будьте готовы тратить на учёбу хотя бы 15 часов в неделю в течение двух или трёх лет. Если вы увлечены компьютерными науками или программированием, хотите развиваться в этих областях, любите учиться, то осваивать курсы и работать над проектами будет интересно и полезно.

Задать вопросы про набор можно в телеграм канале или по почте info@compscicenter.ru.

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

Немного истории

При переходе с Windows на Linux мне пришлось изучать не только новую операционную систему, но и новую систему контроля версий - GIT. Очень быстро я проникся идеей о том, что работать с GIT нужно из консоли и только визуализацию дерева коммитов оставить на откуп графическим утилитам. Отсмотрев несколько графических программ, я остановил свой выбор на QGit. Утилита показалась достаточно минималистичной и симпатичной в графическом плане. К тому же, она была написана на Qt, что давало мне потенциальную возможность заглянуть под капот QGit (я - разработчик ПО и последние лет десять создаю программы с использованием Qt Framework).

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

Первые опыты

Вхождение в чужой проект - достаточно трудоемкое занятие. Мне потребовалось почти две недели, чтобы составить представление о том, как QGit устроен изнутри. Потраченные усилия оказались не напрасны, проблему с отображением кириллических символов удалось локализовать и исправить. Изменения были приняты в основной репозиторий QGit. Далее последовали несколько небольших доработок по улучшению юзабилити интерфейса, они тоже были приняты мантейнером. А вот предложение добавить в проект поддержку стандарта C++11 было отклонено. Мантейнер пояснил, что на данный момент есть еще много разработчиков использующих компиляторы без поддержки C++11. На дворе был 2016 год... С этого момента все доработки выполнялись в моем форке. За следующие два года было выполнено более 30 изменений, среди них пара существенных:

• переработана реализация внутреннего кэша, используемого для построения дерева коммитов;

• значительное ускорение построения дерева коммитов для проектов с большой историей.

При этом, форк периодически синхронизировался с основным проектом.

Рубикон

Для меня QGit, без преувеличения, программа "на каждый день" :). Частенько приходится работать в выходные или заниматься проектами подобными этому. И несмотря на то, что QGit меня практически полностью устраивал, одной функции очень сильно не хватало. Речь идет о проверке орфографии при создании комментария для коммита.

Уже в 2018 году у меня было понимание, что проверку орфографии нужно было внедрять в QGit, вопрос состоял только в том, когда и какими средствами? Реализация нового функционала и фикс мелких ошибок это совсем не одно и тоже. Вдобавок, у меня была внутренняя дилемма: нужно ли сохранять исходную кодовую стилистику проекта или же использовать более агрессивный подход по модификации кода, привнося в него сторонние библиотеки и собственные наработки в виде зависимостей. Перспективы, что мою работу примут в основную ветку, были туманны. Теоретически это могло произойти, но пришлось бы вести долгую переписку, убеждая мантейнера в ценности вносимых изменений. С другой стороны, использование собственных наработок делало рабочий процесс более комфортным и экономило время. Последний фактор оказался решающим. Так я перешел психологический "Рубикон".

Механизм проверки орфографии

Процесс проверки орфографии можно разбить на два шага:

• определение языка проверяемого слова;

• собственно, сама проверка орфографии с использованием словаря для языка определенного на первом шаге.

Существует несколько добротно проработанных open-source решений для детектирования языка. Даже есть реализации под GPU. К сожалению, слово "добротное" так же подразумевает под собой "тяжелое" и этот факт мне сильно не нравился. Поясню в чем дело: одна из сильных сторон QGit - быстрый старт. Приложение запускается за 1-2 секунды, при этом дерево коммитов уже построено, можно работать. Это позволяет многократно открывать/закрывать QGit без потери комфорта использования. Долгая инициализация механизма проверки орфографии могла изменить это обстоятельство не в лучшую сторону, поэтому тяжелые решения были отброшены.

На момент старта работ, у меня был небольшой опыт использования библиотеки Sonnet. Её я и взял в качестве кандидата. Забегая вперед, скажу, что в проекте от Sonnet мало что осталось: пара функций по подчеркиванию слов красной волнистой линией и пара переработанных утилит по генерации языковых триграмм. Но, обо все по порядку. Строго говоря, Sonnet не обладает функционалом для проверки орфографии, а является лишь оберткой для специализированных библиотек, таких как aspell, hunspell. С другой стороны, специализированные библиотеки не умеют определять язык проверяемых слов, это как раз и делает для них Sonnet. У меня не было намерения использовать Sonnet "как есть", от этой библиотеки мне нужен был только механизм определения языка. Даже не так, не сам механизм, а принципы его функционирования, потому что к качеству работы механизма были вопросы.

Что же не так с Sonnet? Детектирующий механизм определяет язык не для отдельного слова, а целиком для строки (фразы). Вероятно, для текста большого объема такой подход является оправданным, но у него есть существенный недостаток: если в строке встречается слово из другого языка, оно всегда будет детектироваться как ошибочное независимо от того, правильно оно написано или нет. Комментарии к коммитам как раз являются случаем, когда русскоязычные и англоязычные слова могут использоваться в одной строке. Разбирая исходный код Sonnet, я наткнулся на флаги, которые, могли активировать режим детектирования по отдельным словам. Но на тот момент это было не важно, я уже знал, что определение языка по строке - не самая большая проблема. Дело в том, что подход используемый в Sonnet не отличается высокой точностью детектирования. Список языковых триграмм насчитывает всего 300 элементов (для каждого языка), что недостаточно для надежной работы механизма. При этом, тригаммы содержат пробельные символы (прямое следствие детектирования по строке), что еще больше ухудшает ситуацию. Мой опыт эксплуатации механизма показал, что даже 3000 триграмм (без пробельных символов) могут давать сбои при детектировании русского языка. Стабильный результат был достигнут только при 5000. Английскому языку достаточно всего 2000 триграмм.

Понимая, что 300 триграмм явно недостаточно для уверенной работы, разработчики Sonnet решили подстраховаться альтернативными механизмами. Второй уровень детектирования предполагает анализ юникод-символов строки/слов на принадлежность к различным языковым группам, далее делается предположение о языке (более подробно об этом методе рассказать не могу, так как просматривал его поверхностно). Для особо тяжелых случаев существует третий уровень. Он мне особенно понравился! Слова по очереди отправляются в механизм проверки орфографии (aspell, hunspell). Если механизм проверки орфографии возвращает "успех", то запоминается язык словаря. Далее по совокупности таких проверок делается вывод о языке. Спрашивается: "Зачем тогда в начале с триграммами морочиться было!?"

В QGit используется единственный механизм - детектирование по триграммам, но в более надежном варианте (5000 элементов, триграммы без пробельных символов). Язык детектируется для каждого слова. Проверка орфографии выполняется при помощи hunspell, сейчас это наиболее популярная библиотека. Закомментированные строки не проверяются.

Список изменений

Существенные

• проверка орфографии при создании коммита;

• ускорение построения дерева коммитов для проектов с большой историей;

• улучшение поддержки юникода.

Несущественные

• закрытие окна консоли при нажатии на "пробел" (кнопка "OK" получает фокус по умолчанию);

• при создании подписи к коммиту нажатие на Ctrl+Enter эквивалентно клику по "OK";

• Shift+! вызывает форму для основного коммита;

• Shift+@ вызывает форму для amend-коммита;

• QGit завершает работу по нажатию на 'Q';

• сохраняется ширина столбцов в дереве коммитов;

• список файлов виден в Init-коммите;

• авто-перенос для длинных однострочных коммитов (отображение в несколько строк);

• диалоговые окна с сообщениями об ошибках отображаются только когда консоль скрыта;

• удалена панель статуса с формы консоли;

• для дерева коммитов запрещен режим DragAndDrop;

• для команды checkout изменена комбинация клавиш: Ctrl+Shift+C -> Ctrl+C;

• добавлена возможность задавать размер иконок;

• идентификатор нулевого коммита не выводится в интерфейс;

• формат конфиг-файла изменен с INI на YAML;

• добавлена возможность скрывать диалог подтверждения при создании коммита;

• исправлен приоритет отображения закладок Log/Diff при обновлении дерева.

Сильно не существенные

• система логирования заменена на ALog (нужно для системы YAML-конфигурирования).

Дистрибутивы

Код форка расположен тут. Собранный пакет под Ubuntu 20.04 можно взять здесь. Так же есть standalone-пакет под Ubuntu 18.04/20.04 содержащий Qt-компоненты и hunspell (устанавливается в /opt).

Минорное заключение

Любой новый функционал, к сожалению, привносит и новые ошибки, это неизбежный процесс. Мои доработки не исключение. Что-то я уже обнаружил сам и исправил, что-то придется найти вам, если конечно решите использовать мой форк.

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

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

Базовая функциональность fzf очень проста: он читает строки из стандартного потока ввода и даёт пользователю интерфейс, чтобы можно было выбрать одну или несколько строк и вписать их в стандартный поток вывода. Вики-страницы этого инструмента содержат массу примеров эффективного применения fzf. Это прекрасный ресурс, я взял несколько функций оттуда в свой репертуар и пользуюсь этими функциями почти каждый день, но в своей работе вы можете обнаружить очень специфические процессы, которых нет в вики, тогда как автоматизировать их было бы полезно.

Чтобы показать, как я подхожу к процессам подобного рода, я расскажу о 4 задачах, с которыми обычно сталкиваюсь. Затем напишу функцию оболочки с fzf, которая сделает работу удобнее. Кроме того, я расположу эти функции в порядке возрастания сложности:

• активация виртуальных сред python;

• удаление веток git;

• переход в пул-реквест;

• создание веток для фич из Issues в JIRA.

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

Последние версии функций, включая варианты для fish, вы найдёте на Github.

Активация виртуальных сред python

Переменные моих виртуальных сред python содержится в файле ~/.venv. Вот, что я обычно делаю, чтобы активировать одну из сред:

• начинаю ввод source ~/.venv/;

• чтобы запустить автозавершение, нажимаю <tab>;

• выбираю среду по желанию;

• добавляю bin/activate и нажимаю <enter>.

Процесс можно улучшить чем-то вроде virtualenvwrapper, но есть и хороший пример с fzf: это простейшее решение, которое может занять всего одну строку.

function activate-venv() {  source "$HOME/.venv/$(ls ~/.venv/ | fzf)/bin/activate"}

activate-venv-simple.bash(download)

Активировать эту функцию можно с помощью команды:

source activate-venv-simple.bash

(добавьте этот код в свой .bashrc, чтобы он выполнялся постоянно), а затем используйте его, как показано ниже.

В окне выбора fzf показывает несколько виртуальных сред; среда активируется, когда строка выбрана.

Меньшая проблема то, что, если выйти из fzf нажатием ctrl-d, скрипт упадет с такой ошибкой:

bash: /home/crepels/.venv//bin/activate: No such file or directory

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

function activate-venv() {  local selected_env  selected_env=$(ls ~/.venv/ | fzf)  if [ -n "$selected_env" ]; then    source "$HOME/.venv/$selected_env/bin/activate"  fi}

Удаление веток git

Другим обнаруженным паттернам самоповторения оказалось удаление веток git. Как только фича смержена в основную ветку или эксперимент больше не нужен, ветка может быть удалена, но обычно я не удаляю её сразу: вместо этого ветки накапливаются, пока их количество не достигает критической точки, в которой навигация по веткам затрудняется. Когда дело в самом деле доходит до удаления веток, картина выглядит так:

• я начинаю ввод git branch -D;

• нажимаю табуляцию, чтобы вызвать автозавершение;

• выбираю ветку, которую, как мне кажется, можно удалить.

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

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

function delete-branches() {  local branches_to_delete  branches_to_delete=$(git branch | fzf --multi)  if [ -n "$branches_to_delete" ]; then     git branch --delete --force $branches_to_delete  fi}

После выполнения source delete-branches-simple.bash мы можем использовать этот код следующим образом.

Код в основном работает, но реализовать эту функциональность можно по-разному. Первый вариант git branch показывает все ветки, включая ту, в которой мы находимся, она отмечена звёздочкой (*). Поскольку нельзя удалить ветку, в которой мы находимся, то и показывать её смысла нет, так что мы можем опустить эту ветку, предоставив вывод git branch команде grep --invert-match

Ещё один способ: мы можем пропустить переменным $branches_to_delete без кавычек в git branch -D. Сделать это нужно потому, что git каждая ветка нужна как отдельный аргумент. Если вы пользуетесь линтером вроде shallcheck, эта строка ему не понравится, поскольку переменные без кавычек могут вызвать глоббинг и разделение слов. В нашем случае срабатывание будет ложным: ветка не может содержать символов глоббинга; тем не менее я думаю, что избегать переменных без кавычек, где это возможно, хорошая практика, и один из способов сделать это пропустить вывод fzf через xargs прямо в git branch -D, а не хранить этот вывод в переменной. Если в xargs добавить опцию --no-run-if-empty, git будет вызываться только в том случае, если была выбрана хотя бы одна ветка.

Наконец, я упоминал, что, чтобы увидеть выбранную ветку, полезно посмотреть на вывод git log. Сделать это можно при помощи опции --preview: значением этой опции может быть какая-нибудь команда, которая будет выполняться всякий раз, когда в fzf будет выбрана новая строка, и вывод будет показан в окне предварительного просмотра. Фигурные скобки в этой команде работают как плейсхолдер, то есть заменяются на текущую выбранную строку.

function delete-branches() {  git branch |    grep --invert-match '\*' |    cut -c 3- |    fzf --multi --preview="git log {} --" |    xargs --no-run-if-empty git branch --delete --force}

Также обратите внимание на то, что вывод git branch пропускается через cut -с -3, которая из каждой строки удаляет 2 пробела. Если посмотреть на вывод git branch, видно, что каждая ветка, за исключением текущей, имеет префикс в 2 пробела. Если их не удалить, команда в --preview будет такой: git log ' branch-name', что приведёт к жалобам git на лишние начальные пробелы. В качестве альтернативы используйте команду git log {..}, которая тоже удалит пробелы из выбранной строки.

Вот пример: мы удаляем те же три ветки, что и выше, но при этом получаем больше информации.

Поток fzf для удаления ветвей в окне предварительного просмотра. Показаны ветки и вывод git log. Ударение ветвей с помощью fzf улучшенная версия.

Локально заходим в пул-реквест

Когда делается код-ревью, полезно бывает переключиться в ветку кода, который вы просматриваете . Интерфейс командной строки от гитхаба упрощает эту задачу: можно просто выполнить в репозитории команду пр pr-checkout. Так вы окажетесь в ветке соответствующего пул-реквеста и уже локально. Но как узнать номер пул-реквеста? Вот что я обычно делал:

• открывал пул-реквест в браузере;

• читал номер в URL;

• переключался на окно терминала и вводил gh pr checkout, а затем номер.

Этот подход работает, когда мы имеем дело с пул-реквестом в 1 или 2 цифры, но, даже когда цифры всего 3, иногда я переключаюсь на браузер, чтобы убедиться, что запомнил номер правильно.

В моём прошлом посте я уже рассказывал, как при помощи gh автоматически опрашивал api Github, чтобы узнать номер пул-реквеста. Вы можете воспользоваться запросом к api, который я показываю ниже:

gh api 'repos/:owner/:repo/pulls'

Этот запрос возвращает массив JSON-объектов по одному объекту на каждый пул-реквест. Нам нужно конвертировать этот массив в подходящий fzf формат по строке на пул-реквест. Если говорить о данных, которые нам нужны, первое это номер пул-реквеста, который мы хотим пропустить через gh checkout. Также нам нужен способ идентифицировать интересный нам пул-реквест, в этом смысле лучший кандидат его заголовок. Чтобы извлечь эту информацию из JSON, мы можем воспользоваться интерполяцией строки в jq.

gh api 'repos/:owner/:repo/pulls' |    jq --raw-output '.[] | "#\(.number) - \(.title)"'

Вот опция сырого вывода --raw-output, которая определяет строку JSON; без неё каждая строка данных будет окружена кавычками. К примеру, если я выполню команду pr checkout https://github.com/junegunn/fzf, она выведет эти строки:

#2368 - ansi: speed up parsing by roughly 7.5x#2349 - Vim plugin fix for Cygwin 3.1.7 and above#2348 - [completion] Default behaviour to use fd if present else use find.#2302 - Leading double-quote for exact match + case sensitive search#2197 - Action accept-1 to accept a single match#2183 - Fix quality issues#2172 - Draft: Introduce --print-selected-count#2131 - #2130 allow sudo -E env fzf completion#2112 - Add arglist support to fzf.vim#2107 - Add instructions on command for installing fzf with Guix and/or Guix System#2077 - Use fzf-redraw-prompt in history widget#2004 - Milis Linux support#1964 - Use tmux shell-command#1900 - Prompt generally signals that the shell is ready#1867 - add {r}aw flag to disable quoting in templates#1802 - [zsh completion] Expand aliases recursively#1705 - Option to select line index of input feed and to output cursor line index#1667 - $(...) calls should be quoted: \"$(...)\"#1664 - Add information about installing using Vundle#1616 - Use the vim-specific shell instead of the environment variable#1581 - add pre / post completion 'hooks'#1439 - Suppress the zsh autocomplete line number output#1299 - zsh completion: Add support for per-command completion triggers.#1245 - Respect switchbuf option#1177 - [zsh] let key bindings be customized through zstyle#1154 - Improve kill completion.#1115 - _fzf_complete_ssh: support Include in ssh configs#559 - [vim] use a window-local variable to find the previous window#489 - Bash: Key bindings fixes

Пропустив их через fzf, мы сможем выбрать какие-то из этих строк и записать их стандартный поток вывода. Нам интересен только номер запятой, так что извлечём его при помощи команды set регулярного выражения с захватом группы. 1-я работающая версия выглядит так:

function pr-checkout() {  local pr_number  pr_number=$(    gh api 'repos/:owner/:repo/pulls' |    jq --raw-output '.[] | "#\(.number) \(.title)"' |    fzf |    sed 's/^#\([0-9]\+\).*/\1/'  )  if [ -n "$pr_number" ]; then    gh pr checkout "$pr_number"  fi}

Попробуем его на репозитории fzf.

Поток fzf в окне выбора показывает заголовки пул-реквестов. Выбирая строку, мы попадаем на соответствующий пул-реквест.

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

В этой функции мы удаляем ветки выше и заполняем окно предварительного просмотра с помощью вызова git log в выбранной ветви. Первой идеей может быть попытка попробовать то, что я уже показывал, то есть сделать запрос к api, чтобы получить информацию о выбранном реквесте. Но если мы выбираем разные ветви, то задержка запроса к api может начать нас раздражать, затрудняя работу. К счастью, запросы api нам больше не понадобятся: все нужные данные у нас уже есть: мы получили их, когда сделали первый запрос. Что нам нужно это дописать шаблон строки jq, чтобы извлечь всю нужную информацию и затем воспользоваться функцией fzf, которая позволяет спрятать информацию входящих строк в окне выбора и показать её в окне предпросмотра.

fzf рассматривает каждую строку как массив полей. По умолчанию поля разделяются последовательностями пробелов (табуляциями и пробелами), но мы можем управлять разделителем с помощью опции --delimiter. Например, если мы зададим --delimiter=',' и передадим строку first,second,third в fzf, то поля будут first,, second и third. Само по себе это бесполезно. Но с помощью опции --with-nth мы можем управлять полями в окне выбора. Например, fzf --with-nth=1,2 будет отображать только первое и второе поля каждой строки. Кроме того, мы видели выше, что можно написать {} в качестве плейсхолдера в команде предварительного просмотра и fzf заменит его текущей выбранной строкой. Но {} это простейшая форма плейсхолдера. Можно указать индексы полей в фигурных скобках, и fzf заменит плейсхолдер этими полями.

Вот пример, где мы используем как --with-nth, так и --preview, а <tab> играет роль разделителя.

echo -e 'first line\tfirst preview\nsecond line\tsecond preview' |    fzf --delimiter='\t' --with-nth=1 --preview='echo {2}'

fzf разбивает каждую строку по символу табуляции; опция --with-nth=1 указывает fzf показать первую часть в окне выбора; {2} в команде предварительного просмотра будет заменена второй частью, и так как она передаётся в echo, то просто отобразится.

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

function pr-checkout() {  local jq_template pr_number  jq_template='"'\'#\(.number) - \(.title)'\'\t'\'Author: \(.user.login)\n'\'Created: \(.created_at)\n'\'Updated: \(.updated_at)\n\n'\'\(.body)'\'"'  pr_number=$(    gh api 'repos/:owner/:repo/pulls' |    jq ".[] | $jq_template" |    sed -e 's/"\(.*\)"/\1/' -e 's/\\t/\t/' |    fzf \      --with-nth=1 \      --delimiter='\t' \      --preview='echo -e {2}' \      --preview-window=top:wrap |    sed 's/^#\([0-9]\+\).*/\1/'  )  if [ -n "$pr_number" ]; then    gh pr checkout "$pr_number"  fi}

Мы немного изменили эту простую функцию. Извлекли шаблон строки jq в переменную, а затем дополнили её информацией об авторе, времени создания пул-реквеста, времени его последнего обновления, а также его описанием . Всю эту информацию мы получили в объекте JSON. Ответьте на этот запрос к api гитхаба: gh api 'repos/:owner/:repo/pulls'.

Обратите внимание, что мы отделили новую информацию номер и заголовок символом табуляции \t. Символ табуляции используется также в качестве разделителя в fzf, затем мы показываем номер пул-реквеста и заголовок в окне выбора (при помощи --with-nth=1), а оставшуюся информацию показываем в окне предварительного просмотра (при помощи --preview='echo -e {2}').

Обратите внимание также, что на этот раз в jq мы не используем опцию --raw-output. Причина немного неочевидна. Строки, которые мы создаём с помощью jq, содержат экранированные символы новой строки. Если мы передадим опцию --raw-output в jq, она будет интерпретировать все экранированные символы, и, в частности, вместо \n отобразится именно новая строка. Вот пример, сравните выходные данные этой команды:

echo '{}' | jq --raw-output '"first\nsecond"'

и команды

echo '{}' | jq '"first\nsecond"'

первая выведет

firstsecond

А вторая вот такую строку:

"first\nsecond"

Первая версия проблематична. Помните, что fzf работает со строками, делает список строк, позволяя пользователю выбрать одну или несколько строк и вывести их. Это означает, что без опции сырого вывода каждый пул-реквест в fzf будет показан как множество строк. И это определённо не то, чего мы хотим. Поэтому позволим jq вывести escape-версию, чтобы гарантировать, что каждый пул-реквест это одна строка.

Однако такой подход вводит новые проблемы, первая мы по-прежнему хотим настоящие символы новой строки, а не символы \n. Эта проблема решается командой echo -e, которая включает интерпретацию escape-символов. Вторая проблема в том, что без опции сырого вывода jq в начале и в конце строки показывает символы кавычек и распечатывает наш разделитель, то есть табуляцию, как символ в escape. Эту проблему мы решим удалением кавычек в ручном режиме и заменой первого escape-символа \t на настоящую табуляцию. Именно это делается в sed после jq.

Наконец, обратите внимание, что мы определили опцию --preview-window=top:wrap, чтобы fzf оборачивал строки в окне предпросмотра и отображал их верхней части экрана, а не справа.

И вот как это выглядит в действии:

Создание веток для фич из проблем (issues) в JIRA

Мы видели выше, как использовать fzf для удаления ветвей git. Теперь давайте посмотрим на противоположную задачу создание новых ветвей. На работе для отслеживания проблем мы используем JIRA. Каждая ветвь функции обычно соответствует какой-то проблеме JIRA. Чтобы поддерживать эту взаимосвязь, я использую схему именования ветвей git, о которой расскажу ниже. Предположим, что проект JIRA называется BLOG, и сейчас я работаю над проблемой BLOG-1232 с названием Добавить в сценарий запуска флаг вывода подробностей. Я называю свою ветку BLOG-1232/add-a-verbose-flag-to-the-startup-script; описание обычно даёт достаточно информации, чтобы определить функцию, которой соответствует ветвь, а часть BLOG-1232 позволяет мне перейти к тикету JIRA, когда я ищу подробности о проблеме.

Вполне понятно, как выглядит рабочий процесс создания этих веток:

• вы открываете issue из JIRA в браузере;

• копируете номер проблемы или запоминаете его;

• переключаетесь на терминал, начинаете вводить git checkout -b BLOG-1232/;

• переключаетесь на браузер и смотрите на название;

• переключаетесь на терминал и добавляете похожее на название в JIRA описание в kebab-cased.

Обычно мне приходится несколько раз переключаться между браузером и терминалом, и я всё равно делаю опечатки в названии ветки.

И это ещё один рабочий процесс, который можно полностью автоматизировать. С проблемами в Jira можно работать так же, как мы работали с пул-реквестами, через API JIRA. Функция, которую мы напишем, подобна pr-checkout, но будет иметь несколько заметных отличий от неё.

Во-первых, от жира нет удобного инструмента, подобного gh, чтобы общаться с её api. Во-вторых, сервер (по крайней мере сервер, с которым работаю я) не разрешает создавать токены доступа, что заставляет меня при доступе к api использовать простые имя пользователя и пароль. Мне не хочется сохранить мой пароль в скрипте оболочки, а точнее, не хочется делать это в незашифрованном файле, поэтому, чтобы пароль хранился безопаснее, воспользуемся secret-tool. Наконец, создание имени ветки требует большего, чем простое извлечение текста; воспользуемся комбинаций cut, sed, и awk.

Давайте сначала посмотрим на скрипт, а потом попробуем понять, как он работает.

function create-branch() {  # The function expectes that username and password are stored using secret-tool.  # To store these, use  # secret-tool store --label="JIRA username" jira username  # secret-tool store --label="JIRA password" jira password  local jq_template query username password branch_name  jq_template='"'\'\(.key). \(.fields.summary)'\'\t'\'Reporter: \(.fields.reporter.displayName)\n'\'Created: \(.fields.created)\n'\'Updated: \(.fields.updated)\n\n'\'\(.fields.description)'\'"'  query='project=BLOG AND status="In Progress" AND assignee=currentUser()'  username=$(secret-tool lookup jira username)  password=$(secret-tool lookup jira password)  branch_name=$(    curl \      --data-urlencode "jql=$query" \      --get \      --user "$username:$password" \      --silent \      --compressed \      'https://jira.example.com/rest/api/2/search' |    jq ".issues[] | $jq_template" |    sed -e 's/"\(.*\)"/\1/' -e 's/\\t/\t/' |    fzf \      --with-nth=1 \      --delimiter='\t' \      --preview='echo -e {2}' \      --preview-window=top:wrap |    cut -f1 |    sed -e 's/\. /\t/' -e 's/[^a-zA-Z0-9\t]/-/g' |    awk '{printf "%s/%s", $1, tolower($2)}'  )  if [ -n "$branch_name" ]; then    git checkout -b "$branch_name"  fi}

В скрипте мы видим три части. Первая часть это команда curl, её переменные. Через них скрипт общается с API JIRA. Затем вывод api конвертируется строки формата, удобного для fzf; это часть скрипта такая же, как у pr-checkout. Наконец, вывод fzf конвертируется формат имени ветки.

Самые существенные изменения в сравнении с pr-checkout эта команда curl. Мы воспользовались конечной точкой поиска JIRA, которая в качестве параметра URL ожидает запрос на языке JQL. В моём случае меня интересуют все проблемы проекта BLOG, которые закреплены за мной, и те, что отмечены строкой In Progress. Строка запроса JQL содержит пробелы, знаки и скобки. Все они недопустимы в url, поэтому их нужно закодировать. Опция curl --data-urlencode автоматически закодирует эти символы. Поскольку в этой опции по умолчанию применяется запрос POST, чтобы переключиться на get, мы должны добавить опцию --get. Также воспользуемся опцией --user, чтобы сообщить curl, что нужно добавить заголовок базовой аутентификации. И последнее: добавим опцию --silent, чтобы опустить информацию о прогрессе выполнения и --compressed, чтобы сэкономить на пропускную способность.

Затем, чтобы конвертировать записи массива в JSON ответе в одну строку, воспользуемся той же техничкой, что и выше, разделив строку поиска в окне предпросмотра по символу табуляции и пропустив вывод через fzf, чтобы позволить пользователю выбрать запись. Вывод fzf будет строкой вроде BLOG-1232. Add a verbose flag to the startup script{...preview part}, чтобы удалить часть предварительного просмотра строки, воспользуемся командой cut. По умолчанию cut в качестве разделителя использует символ табуляции, а опция -f1 сообщает cut, что нужно вывести первое поле. Результат выполнения команды будет таким: BLOG-1232. Add-a-verbose-flag-to-the-startup-scrip. Затем команда sed заменит первую точку на символ табуляции, а все нечисловые и неалфавитные символы на -, сохранив при этом наши табуляции. И вот результат: BLOG-1232<tab>Add-a-verbose-flag-to-the-startup-script. Наконец, awk возьмёт строку, разделит её по табуляции, преобразует её вторую часть в нижний регистр и вернёт обе части символом косой черты в качестве разделителя.

Заключение

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

Представленные мной рабочие процессы могут никак не касаться вас. Но, надеюсь, вам поможет техника в целом: попробовать понаблюдать, как вы добавляете параметр к командам и как этот процесс можно автоматизировать. Параметры могут быть файлами или каким-то местом в системе, расположение которого не меняется, например, виртуальными средами. Или это могут быть параметры, которые пропускаются через другую команду (пример: ветви гита) или через API (номер пул-реквеста или заголовок из JIRA).

Узнайте, как прокачаться в других специальностях или освоить их с нуля:

• Профессия Data Scientist

• Профессия Data Analyst

• Курс по Data Engineering

Git имеет репутацию запутывающего инструмента. Пользователи натыкаются на терминологию и формулировки, которые вводят в заблуждение. Это более всего проявляется в "перезаписывающих" историю командах, таких как git cherry-pick или git rebase. По моему опыту, первопричина путаницы интерпретация коммитов как различий, которые можно перетасовать. Однако коммиты это не различия, а снимки! Я считаю, что Git станет понятным, если поднять занавес и посмотреть, как он хранит данные репозитория. Изучив модель хранения данных мы посмотрим, как новый взгляд помогает понять команды, такие как git cherry-pick и git rebase.

Если хочется углубиться по-настоящему, читайте главу о внутренней работе Git (Git internals) книги Pro Git. Я буду работать с репозиторием git/git версии v2.29.2. Просто повторяйте команды за мной, чтобы немного попрактиковаться.

Хеши идентификаторы объектов

Самое важное, что нужно знать о Git-объектах, это то, что Git ссылается на каждый из них по идентификатору объекта (OID для краткости), даёт объекту уникальное имя.

Чтобы найти OID, воспользуемся командой git rev-parse. Каждый объект, по сути, простой текстовый файл, его содержимое можно проверить командой git cat-file -p.

Мы привыкли к тому, что OID даны в виде укороченной шестнадцатеричной строки. Строка рассчитана так, чтобы только один объект в репозитории имел совпадающий с ней OID. Если запросить объект слишком коротким OID, мы увидим список соответствующих подстроке OID.

$ git cat-file -t e0c03error: short SHA1 e0c03 is ambiguoushint: The candidates are:hint: e0c03f27484 commit 2016-10-26 - contrib/buildsystems: ignore irrelevant files in Generators/hint: e0c03653e72 treehint: e0c03c3eecc blobfatal: Not a valid object name e0c03

Блобы это содержимое файлов

На нижнем уровне объектной модели блобы содержимое файла. Чтобы обнаружить OID файла текущей ревизии, запустите git rev-parse HEAD:<path>, а затем, чтобы вывести содержимое файла git cat-file -p <oid>.

$ git rev-parse HEAD:README.mdeb8115e6b04814f0c37146bbe3dbc35f3e8992e0$ git cat-file -p eb8115e6b04814f0c37146bbe3dbc35f3e8992e0 | head -n 8[![Build status](http://personeltest.ru/aways/github.com/git/git/workflows/CI/PR/badge.png)](http://personeltest.ru/aways/github.com/git/git/actions?query=branch%3Amaster+event%3Apush)Git - fast, scalable, distributed revision control system=========================================================Git is a fast, scalable, distributed revision control system with anunusually rich command set that provides both high-level operationsand full access to internals.

Если я отредактирую файл README.md на моём диске, то git status предупредит, что файл недавно изменился, и хэширует его содержимое. Когда содержимое файла не совпадает с текущим OID в HEAD:README.md, git status сообщает о файле как о "модифицированном на диске". Таким образом видно, совпадает ли содержимое файла в текущей рабочей директории с ожидаемым содержимым в HEAD.

Деревья это списки каталогов

Обратите внимание, что блобы хранят содержание файла, но не его имя. Имена берутся из представления каталогов Git деревьев. Дерево это упорядоченный список путей в паре с типами объектов, режимами файлов и OID для объекта по этому пути. Подкаталоги также представлены в виде деревьев, поэтому деревья могут указывать на другие деревья!

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

$ git rev-parse HEAD^{tree}75130889f941eceb57c6ceb95c6f28dfc83b609c$ git cat-file -p 75130889f941eceb57c6ceb95c6f28dfc83b609c  | head -n 15100644 blob c2f5fe385af1bbc161f6c010bdcf0048ab6671ed    .cirrus.yml100644 blob c592dda681fecfaa6bf64fb3f539eafaf4123ed8    .clang-format100644 blob f9d819623d832113014dd5d5366e8ee44ac9666a    .editorconfig100644 blob b08a1416d86012134f823fe51443f498f4911909    .gitattributes040000 tree fbe854556a4ae3d5897e7b92a3eb8636bb08f031    .github100644 blob 6232d339247fae5fdaeffed77ae0bbe4176ab2de    .gitignore100644 blob cbeebdab7a5e2c6afec338c3534930f569c90f63    .gitmodules100644 blob bde7aba756ea74c3af562874ab5c81a829e43c83    .mailmap100644 blob 05f3e3f8d79117c1d32bf5e433d0fd49de93125c    .travis.yml100644 blob 5ba86d68459e61f87dae1332c7f2402860b4280c    .tsan-suppressions100644 blob fc4645d5c08bd005238fc72cfa709495d8722e6a    CODE_OF_CONDUCT.md100644 blob 536e55524db72bd2acf175208aef4f3dfc148d42    COPYING040000 tree a58410edddbdd133cca6b3322bebe4fb37be93fa    Documentation100755 blob ca6ccb49866c595c80718d167e40cfad1ee7f376    GIT-VERSION-GEN100644 blob 9ba33e6a141a3906eb707dd11d1af4b0f8191a55    INSTALL

Деревья дают названия каждому подпункту и также содержат такую информацию, как разрешения на файлы в Unix, тип объекта (blob или tree) и OID каждой записи. Мы вырезаем выходные данные из 15 верхних записей, но можем использовать grep, чтобы обнаружить, что в этом дереве есть запись README.md, которая указывает на предыдущий OID блоба.

$ git cat-file -p 75130889f941eceb57c6ceb95c6f28dfc83b609c | grep README.md100644 blob eb8115e6b04814f0c37146bbe3dbc35f3e8992e0    README.md

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

Само дерево не знает, где внутри репозитория оно находится, то есть указывать на дерево роль объектов. Дерево, на которое ссылается <ref>^{tree}, особое это корневое дерево. Такое обозначение основано на специальной ссылке из вашего коммита.

Коммиты это снапшоты

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

В коммите есть список родительских коммитов, соответствующих предыдущим снимкам. Коммит без родителей это корневой коммит, а коммит с несколькими родителями это коммит слияния.

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

Например, коммит в v2.29.2 в Git-репозитории описывает этот релиз, также он авторизован, а его автор член команды разработки Git.

$ git rev-parse HEAD898f80736c75878acc02dc55672317fcc0e0a5a6/c/_git/git ((v2.29.2))$ git cat-file -p 898f80736c75878acc02dc55672317fcc0e0a5a6tree 75130889f941eceb57c6ceb95c6f28dfc83b609cparent a94bce62b99be35f2ee2b4c98f97c222e7dd9d82author Junio C Hamano <gitster@pobox.com> 1604006649 -0700committer Junio C Hamano <gitster@pobox.com> 1604006649 -0700Git 2.29.2Signed-off-by: Junio C Hamano <gitster@pobox.com>

Заглянув немного дальше в историю при помощи git log, мы увидим более подробное сообщение о коммите, оно рассказывает об изменении между этим коммитом и его родителем.

$ git cat-file -p 16b0bb99eac5ebd02a5dcabdff2cfc390e9d92eftree d0e42501b1cf65395e91e22e74f75fc5caa0286eparent 56706dba33f5d4457395c651cf1cd033c6c03c7aauthor Jeff King <peff@peff.net> 1603436979 -0400committer Junio C Hamano <gitster@pobox.com> 1603466719 -0700am: fix broken email with --committer-date-is-author-dateCommit e8cbe2118a (am: stop exporting GIT_COMMITTER_DATE, 2020-08-17)rewrote the code for setting the committer date to use fmt_ident(),rather than setting an environment variable and letting commit_tree()handle it. But it introduced two bugs:- we use the author email string instead of the committer email- when parsing the committer ident, we used the wrong variable tocompute the length of the email, resulting in it always being azero-length stringThis commit fixes both, which causes our test of this option via therebase "apply" backend to now succeed.Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

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

• Квадраты это блобы. Они представляют содержимое файла.

• Треугольники это деревья. Они представляют каталоги.

• Круги это коммиты. Снапшоты во времени.

Ветви это указатели

В Git мы перемещаемся по истории и вносим изменения, в основном не обращаясь к OID. Это связано с тем, что ветви дают указатели на интересующие нас коммиты. Ветка с именем main на самом деле ссылка в Git, она называется refs/heads/main. Файлы ссылок буквально содержат шестнадцатеричные строки, которые ссылаются на OID коммита. В процессе работы эти ссылки изменяются, указывая на другие коммиты.

Это означает, что ветки существенно отличаются от Git-объектов. Коммиты, деревья и блобы неизменяемы (иммутабельны), это означает, что вы не можете изменить их содержимое. Изменив его, вы получите другой хэш и, таким образом, новый OID со ссылкой на новый объект!

Ветки именуются по смыслу, например, trunk [ствол] или my-special-object. Ветки используются, чтобы отслеживать работу и делиться её результатами. Специальная ссылка HEAD указывает на текущую ветку. Когда коммит добавляется в HEAD, он автоматически обновляется до нового коммита ветки. Создать новую ветку и обновить HEAD можно при помощи флага git -c:

$ git switch -c my-branchSwitched to a new branch 'my-branch'$ cat .git/refs/heads/my-branch1ec19b7757a1acb11332f06e8e812b505490afc6$ cat .git/HEADref: refs/heads/my-branch

Обратите внимание: когда создавалась my-branch, также был создан файл (.git/refs/heads/my-branch) с текущим OID коммита, а файл .git/HEAD был обновлён так, чтобы указывать на эту ветку. Теперь, если мы обновим HEAD, создав новые коммиты, ветка my-branch обновиться так, что станет указывать на этот новый коммит!

Общая картина

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

Время на диаграмме отсчитывается слева направо. Стрелки между коммитом и его родителями идут справа налево. У каждого коммита одно корневое дерево. HEAD указывает здесь на ветку main, а main указывает на самый недавний коммит.

Корневое дерево у этого коммита раскинулось полностью под ним, у остальных деревьев есть указывающие на эти объекты стрелки, потому что одни и те же объекты доступны из нескольких корневых деревьев! Эти деревья ссылаются на объекты по их OID (их содержимое), поэтому снимкам не нужно несколько копий одних и тех же данных. Таким образом, объектная модель Git образует дерево хешей.

Рассматривая объектную модель таким образом, мы видим, почему коммиты это снимки: они непосредственно ссылаются на полное представление рабочего каталога коммита!

Вычисление различий

Несмотря на то, что коммиты это снимки, мы часто смотрим на коммит в его историческом представлении или видим его на GitHub как diff. На самом же деле сообщение о коммите часто ссылается на различие. генерируемое динамически из данных снимка путём сравнения корневых деревьев коммита и его родителя. Git может сравнить не только соседние снимки, но и два любых снимка вообще.

Чтобы сравнить два коммита, сначала рассмотрите их корневые деревья, которые почти всегда отличаются друг от друга. Затем в поддеревьях выполните поиск в глубину, следуя по парам, когда пути для текущего дерева имеют разные OID.

В примере ниже корневые деревья имеют разные значения для docs, поэтому мы рекурсивно обходим их. Эти деревья имеют разные значения для M.md, таким образом, два блоба сравниваются построчно и отображается их различие. Внутри docs N.md по-прежнему тот же самый, так что пропускаем их и возвращаемся к корневому дереву. После этого корневое дерево видит, что каталоги things имеют одинаковые OID, так же как и записи README.md.

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

Теперь, когда понятно, что коммиты это снимки, можно динамически вычислять разницу между любыми двумя коммитами. Почему тогда этот факт не общеизвестен? Почему новые пользователи натыкаются на идею о том, что коммит это различие?

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

Подождите, а что такое патч?

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

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

Git может преобразовать коммит в патч командой git format-patch. Затем патч может быть применён к Git-репозиторию командой git application. В первые дни существования открытого исходного кода такой способ обмена доминировал, но большинство проектов перешли на обмен коммитами непосредственно через пул-реквесты.

Самая большая проблема с тем, чтобы делиться исправлениями в том, что патч теряет родительскую информацию, а новый коммит имеет родителя, который одинаков с вашим HEAD. Более того, вы получаете другой коммит, даже если работаете с тем же родителем, что и раньше, из-за времени коммита, но при этом коммиттер меняется! Вот основная причина, по которой в объекте коммита Git есть разделение на "автора", и "коммиттера".

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

Идея перемещения патчей с места на место перешла в несколько команд Git как "перемещение коммитов". На самом же деле различие коммитов воспроизводится, создавая новые коммиты.

Если коммиты это не различия, что делает git cherry-pick?

Команда [git cherry-pick создаёт новый коммит с идентичным отличием от <oid>, родитель которого текущий коммит. Git в сущности выполняет такие шаги:

1. Вычисляет разницу между <oid> коммита и его родителя.

2. Применяет различие к текущему HEAD.

3. Создаёт новый коммит, корневое дерево которого соответствует новому рабочему каталогу, а родитель созданного коммита HEAD.

4. Перемещает ссылку HEAD в этот новый коммит.

После создания нового коммита вывод git log -1 -p HEAD должен совпадать с выводом git log -1 -p <oid>.

Важно понимать, что мы не "перемещали" коммит так, чтобы он был поверх нашего текущего HEAD, мы создали новый коммит, и его вывод diff совпадает со старым коммитом.

А что делает git rebase?

Команда git rebase это способ переместить коммиты так, чтобы получить новую историю. В простой форме это на самом деле серия команд git cherry-pick, которая воспроизводит различия поверх другого, отличного коммита.

Самое главное: git rebase <target> обнаружит список коммитов, доступных из HEAD, но недоступных из <target>. С помощью команды git log --online <target>...HEAD вы можете отобразить их самостоятельно.

Затем команда rebase просто переходит в местоположению <target> и выполняет команды git cherry-pick в этом диапазоне коммитов, начиная со старых. В конце мы получили новый набор коммитов с разными OID, но схожих с первоначальным диапазоном.

Для примера рассмотрим последовательность из трёх коммитов в текущей ветке HEAD с момента разветвления target. При запуске git rebase target? чтобы определить список коммитов A, B, и C, вычисляется общая база P. Затем поверх target они выбираются cherry-pick, чтобы создать новые коммиты A', B' и C'.

Коммиты A', B' и C' это совершенно новые коммиты с общим доступом к большому количеству информации через A, B и C, но они представляют собой отдельные новые объекты. На самом деле старые коммиты существуют в вашем репозитории до тех пор, пока не начнётся сбор мусора.

С помощью команды git range-diff мы даже можем посмотреть на различие двух диапазонов коммитов! Я использую несколько примеров коммитов в репозитории Git, чтобы сделать rebase на тег v2.29.2, а затем слегка изменю описание коммита.

$ git checkout -f 8e86cf65816$ git rebase v2.29.2$ echo extra line >>README.md$ git commit -a --amend -m "replaced commit message"$ git range-diff v2.29.2 8e86cf65816 HEAD1:  17e7dbbcbc = 1:  2aa8919906 sideband: avoid reporting incomplete sideband messages2:  8e86cf6581 ! 2:  e08fff1d8b sideband: report unhandled incomplete sideband messages as bugs    @@ Metadata     Author: Johannes Schindelin <Johannes.Schindelin@gmx.de>           ## Commit message ##    -    sideband: report unhandled incomplete sideband messages as bugs    +    replaced commit message         -    It was pretty tricky to verify that incomplete sideband messages are    -    handled correctly by the `recv_sideband()`/`demultiplex_sideband()`    -    code: they have to be flushed out at the end of the loop in    -    `recv_sideband()`, but the actual flushing is done by the    -    `demultiplex_sideband()` function (which therefore has to know somehow    -    that the loop will be done after it returns).    -    -    To catch future bugs where incomplete sideband messages might not be    -    shown by mistake, let's catch that condition and report a bug.    -    -    Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>    -    Signed-off-by: Junio C Hamano <gitster@pobox.com>    + ## README.md ##    +@@ README.md: and the name as (depending on your mood):    + [Documentation/giteveryday.txt]: Documentation/giteveryday.txt    + [Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt    + [Documentation/SubmittingPatches]: Documentation/SubmittingPatches    ++extra line           ## pkt-line.c ##     @@ pkt-line.c: int recv_sideband(const char *me, int in_stream, int out)

Обратите внимание: результирующий range-diff утверждает, что коммиты 17e7dbbcbc и 2aa8919906 "равны", а это означает, что они будут генерировать один и тот же патч. Вторая пара коммитов различается: показано, что сообщение коммита изменилось, есть правка в README.md, которой не было в исходном коммите.

Если пройти вдоль дерева, вы увидите, что история коммитов всё ещё существует у обоих наборов коммитов. Новые коммиты имеют тег v2.29.2 в истории это третий коммит, тогда как старые имеют тег v2.28.0 болеее ранний, а в истории он также третий.

$ git log --oneline -3 HEADe08fff1d8b2 (HEAD) replaced commit message2aa89199065 sideband: avoid reporting incomplete sideband messages898f80736c7 (tag: v2.29.2) Git 2.29.2$ git log --oneline -3 8e86cf658168e86cf65816 sideband: report unhandled incomplete sideband messages as bugs17e7dbbcbce sideband: avoid reporting incomplete sideband messages47ae905ffb9 (tag: v2.28.0) Git 2.28

Если коммиты не отличия, тогда как Git отслеживает переименования?

Внимательно посмотрев на объектную модель, вы заметите, что Git никогда не отслеживает изменения между коммитами в сохранённых объектных данных. Можно задаться вопросом: "Откуда Git знает, что произошло переименование?"

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

Вместо этого Git пытается обнаружить переименования во время динамического вычисления различий. Есть два этапа обнаружения переименований: именно переименования и редактирования.

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

На первом этапе этого алгоритма сопоставления рассматриваются OID добавленных и удалённых путей и проверяется их точное соответствие. Такие точные совпадения соединяются в пары.

Вторая стадия дорогая часть вычислений: как обнаружить файлы, которые были переименованы и отредактированы? Посмотреть каждый добавленный файл и сравните этот файл с каждым удалённым, чтобы вычислить показатель схожести в процентах к общему количеству строк. По умолчанию что-либо, что превышает 50 % общих строк, засчитывается как потенциальное редактирование с переименованием. Алгоритм сравнивает эти пары до момента, пока не найдёт максимальное совпадение.

Вы заметили проблему? Этот алгоритм прогоняет A * D различий, где A количество добавлений и D количество удалений, то есть у него квадратичная сложность! Чтобы избежать слишком долгих вычислений по переименованию, Git пропустит часть с обнаружением редактирований с переименованием, если A + D больше внутреннего лимита. Ограничение можно изменить настройкой опции diff.renameLimit в конфигурации. Вы также можете полностью отказаться от алгоритма, просто отключив diff.renames.

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

1. Переименовать все файлы без изменения блобов.

2. Заменить строки, чтобы изменить блобы без изменения файлов.

Эти два шага позволили мне быстро выполнить git log --follow -- <path>, чтобы посмотреть историю переименовывания.

$ git log --oneline --follow -- Scalar/CommandLine/ScalarVerb.cs4183579d console: remove progress spinners from all commands5910f26c ScalarVerb: extract Git version check...9f402b5a Re-insert some important instances of GVFS90e8c1bd [REPLACE] Replace old name in all filesfb3a2a36 [RENAME] Rename all filescedeeaa3 Remove dead GVFSLock and GitStatusCache codea67ca851 Remove more dead hooks code...

Я сократил вывод: два этих последних коммита на самом деле не имеют пути, соответствующего Scalar/CommandLine/ScalarVerb.cs, вместо этого отслеживая предыдущий путь GVSF/GVFS/CommandLine/GVFSVerb.cs, потому что Git распознал точное переименование содержимого из коммита fb3a2a36 [RENAME] Rename all files.

Не обманывайтесь больше

Теперь вы знаете, что коммиты это снапшоты, а не различия! Понимание этого поможет вам ориентироваться в работе с Git.

И теперь мы вооружены глубокими знаниями объектной модели Git. Не важно, какая у вас специализация, frontend, backend, или вовсе fullstack вы можете использовать эти знания, чтобы развить свои навыки работы с командами Git'а или принять решение о рабочих процессах в вашей команде. А к нам можете приходить за более фундаментальными знаниями, чтобы иметь возможность повысить свою ценность как специалиста или вовсе сменить сферу.

Узнайте, как прокачаться в других специальностях или освоить их с нуля:

• Профессия Data Scientist

• Профессия Data Analyst

• Курс по Data Engineering

В последние несколько лет в среде технических писателей все больше на слуху концепция Docs as Code. Если вы раньше не сталкивались с этим термином, он обозначает подход к разработке технической документации с использованием тех же инструментов и процессов, что и написание кода. Если DocOps это про процессы и коллаборацию, то Docs as Code про инструментарий, при помощи которого мы несмотря ни на что. Мы выбрали этот подход, когда создавали портал документации Plesk.

В этой статье я кратко расскажу, что такое Docs as Code и зачем оно нужно, а затем дам несколько советов относительно того, как это чудо враждебной техники внедрять, сдобрив всю историю рассказами о тех граблях, на которые мы наступили, топая в светлое будущее. Я старался писать такую статью, которая пригодилась бы мне в 2017 году, когда мы эту кашу заваривали.

(N.B. Сразу оговорюсь, что эта статья - обзорная, в ней нет огрызков конфигов или примеров кода. Если вы уже знаете теорию и ищете, как конкретно пропатчить KDE2 под FreeBSD, статья может быть вам не очень интересна).

Акт 1: Теория

Давным-давно, в далёкой-далёкой галактике

Начнем от противного. Чтобы лучше понять преимущества Docs as Code, посмотрим, как документацию писали (а много где и продолжают писать) мои коллеги в компаниях по всему миру. Как правило, выглядит это так:

• Документацию пишут и поддерживают технические писатели и только они.

• Для разработки и публикации используются специализированные проприетарные инструменты, такие как MadCap Flare, Adobe RoboHelp, или Author-it. Реже Wiki или Confluence.

• Технические писатели работают обособленно. Что происходит у них в отделе, никто в конторе не знает и особо этим не интересуется. Взаимодействие на уровне "разработчик заметил ошибку в примере кода и завел баг в Jira", так как с инструментами технических писателей разработчик не знаком и доступа туда, где хранятся доки, у него нет.

Окей, в чем недостатки status quo? Их несколько:

• Отсутствие интереса к документации у большинства сотрудников. Хороша документация разрабатываемых продуктов или плоха никто не знает, и никому до этого нет дела. Не мой цирк, не мои обезьяны.

• Плохая коллаборация. Чтобы исправить опечатку в документации, разработчик или сотрудник поддержки должен написать письмо или завести баг, и станут ли они это делать - бабушка надвое сказала. Это лишний геморрой, а у них и так работы по горло. Процесс совместного ревью также затруднен. Чтобы сделать ревью документа, его нужно выгрузить в гуглдок или файл MS Word, отправить по почте нескольким людям, принять от них комментарии в документах и потом свести их воедино. Ревьюеры не видят комментарии друг друга, делают двойную работу и противоречат друг другу. Это неудобно и техническому писателю, и проверяющему.

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

• Стоимость. Лицензия на широко используемый продукт MadCap Flare обойдется вам в $149 на человека в месяц. Хотите воспользоваться облачным решением от MadCap? Готовьте $300. Незначительная сумма для большой организации. Большой удар по карману для маленькой фирмы или стартапа, еще не нашедшего стабильный источник финансирования.

Конечно, ни один из этих недостатков не является фатальным. Документация создавалась и еще долгие годы будет создаваться при помощи традиционных подходов и инструментов. Однако, если есть альтернатива, важно знать, в чем она заключается и чем она лучше. Что может нам предложить Docs as Code? Давайте узнаем вместе.

Дивный новый мир

Docs as Code это подход к разработке технической документации, который выглядит следующим образом:

• Документация пишется не в плейнтексте и не в формате WYSIWYG, а на языке разметки (например, Markdown, reStructuredText, Asciidoc).

• Документация хранится в репозитории Git.

• Документация собирается в нужный формат при помощи генератора статических сайтов (Sphinx, Hugo, Jekyll, MkDocs). Форматов может быть сразу много: HTML, PDF, DOCX и так далее.

• Документация пишется и обновляется коллаборативно.

К чему эти сложности?

Резонный вопрос. Какую головную боль лечит Docs as Code и в чем его преимущества перед классическим подходом? Преимущества есть, и их немало:

• Docs as Code использует знакомые разработчикам процессы и инструменты, что помогает вовлечь их в процесс создания документации. Это может быть большим подспорьем, если в вашей организации нет выделенного технического писателя и разработкой документации для продукта занимаются сами разработчики. Чудес, правда, ждать не стоит. Для того, чтобы и все заверте, скорее всего, придется терпеливо приучать разработчиков: Василий, смотри, вот ты десять минут заводил баг в Jira, заполнял все необходимые поля и расписывал по шаблону действительность/ожидания только для того, чтобы мы в лоб заменили на по лбу. А что бы было просто не кинуть нам пулл реквест? Быстрее и проще же.

• Использование репозиториев Git и связанных с ними процессов обеспечивает возможность поддерживать документацию для разных версий продукта, облегчает коллаборацию между сотрудниками, позволяет отслеживать авторов внесенных изменений, и дает возможность быстро откатить эти изменения, если нужно. До начала использования Docs as Code у меня в практике был случай, когда я, неправильно сориентировавшись в обстановке, дал сотруднику задачу, которую тот выполнял полдня. Через пару часов выяснилось, что внесенные изменения нужно откатить, чем я лично и занимался до самого вечера. Сейчас подобный конфуз решился бы за несколько минут.

• Использование генератора статических сайтов для публикации приносит с собой все связанные с этим преимущества - сайт документации грузится быстро и на нем нечего ломать.

• В отличие от проприетарных инструментов для разработки документации, функциональность инструментов Docs as Code безгранично расширяема и позволяет создать настолько мощную (или, наоборот, простую и дешевую) систему, насколько нужно именно вашей организации.

• Значительное (в несколько раз) сокращение временных затрат на рутинные операции. Публикация при помощи проприетарных инструментов запускается вручную и выдает через какое-то время готовый документ в формате .html или .pdf. Разместить его онлайн ваша забота. В результате имеем долгие, многоступенчатые процедуры публикации, требующие ручных действий на каждом из шагов. Публикация же с помощью Docs as Code может быть сведена к выполнению одной команды или даже полностью автоматизирована.

• Проприетарные инструменты для разработки документации требуют покупки одной или нескольких лицензий (зачастую весьма дорогих). Весь же цикл разработки документации по методологии Docs as Code можно выстроить при помощи свободного программного обеспечения. Это также порадует тех, кто отказывается от использования проприетарного ПО из идейных соображений.

Хотите страшную сказку на ночь? Я расскажу, как было у нас до того, как в Plesk появился Docs as Code. Мы использовали продукт под названием Author-It, и публикация документации с его помощью выглядела так:

1. Делаешь выгрузку HTML. Это могло занять от пяти минут до часа, в зависимости от размера гайда.

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

3. Пакуешь все это дело в архив и заливаешь по FTP на сервер.

4. Запускаешь сборку и ждешь еще полчасика. Молишься, чтобы не упало. Если упадёт, надо перезапускать.

Всё это счастье происходило при каждой публикации. Даже если ты поправил опечатку в одну букву. Это был неописуемо нудный процесс, жравший непристойное количество времени и часто приводивший к ошибкам. Забыл накатить стили перед публикацией? GOTO 20. Забыл накатить стили и уже успел удалить сгенерированные Author-it html-ки? GOTO 10. Теперь же наша документация собирается и публикуется по мерджу пулл реквеста автоматически. Автоматически, Карл! Пока не попробуешь сам, не поймешь, насколько же это круто! А сэкономленное время и внимание можно пустить на решение интересных задач.

Подводные камни

Перечитал предыдущий абзац - звучит, как будто я этим Docs as Code торгую. Что же, у нас на руках идеальное решение? Необязательно. Как и у любого другого подхода, у него есть своя специфика и недостатки:

• Отсутствие готовой, коробочной версии продукта. Все инструменты, нужные для Docs as Code, доступны, но запускать и настраивать систему вам придется самостоятельно. Будьте готовы к тому, что создание, обслуживание и совершенствование системы публикации документации потребует времени и технической экспертизы.

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

• Вашим техническим писателям нужно будет освоить работу с Git хотя бы на базовом уровне (git checkout/pull/commit/push + разрешение конфликтов при слиянии). Поначалу с этим возникнут трудности, и производительность может пострадать.

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

Антракт

Теперь вы знаете, что такое Docs as Code, и дальше рекомендуется читать, только если вам интересно не только что, но и как. Наше путешествие к Docs as Code началось в 2017 году. У нас было много энтузиазма и мало практического опыта, поэтому мы провели в пути дольше, чем планировали, и набили немало шишек. Об этом и пойдет речь дальше.

Но сперва я сделаю еще один реверанс. Прежде чем читать про как, давайте подумаем про зачем. Docs as Code в тренде, но не стоит бросаться внедрять хайповую технологию, не задав себе вопрос чтобы что? В нашем случае ответ выглядел следующим образом:

• Мы хотели ускорить и упростить процесс публикации - он занимал много времени и требовал ряда ручных действий в независимости от объема внесенных изменений.

• Нам нужна была поддержка версионирования, а Author-It не мог в него от слова совсем. Author-It позволял хранить и публиковать документацию только для одной версии продукта. Если нужно было внести изменения в документацию для более ранней версии Plesk, приходилось править HTML руками.

• Мы хотели сделать более удобным процесс ревью. Author-It умел выгружать топики документации в .doc, который потом высылался на ревью ПМу + разработчику + тестировщику. Сводить комментарии и изменения из нескольких вордовых файлов в один было тем еще удовольствием.

• Также хотелось оставить в прошлом некоторые заскоки Author-It. Например, он позволял молча и без подтверждения выкинуть из структуры гайда топик со всеми его подтопиками. И возможности откатить эту операцию при помощи Ctrl + Z не было. Сами топики при этом не удалялись, страдала только структура, и в теории ее можно было воссоздать руками. На практике было быстрее и проще зайти по RDP на виртуальную машинку, где крутилась серверная часть Author-It, развернуть более старый бэкап базы MSSQL, в которой Author-It хранил всю информацию, выгрузить неповрежденную структуру гайда в XML, снова подключить актуальную базу, удалить гайд, структура которого пострадала, а затем импортировать его из XML. Не шучу, время от времени приходилось заниматься подобным шаманством.

Мы рассматривали различные варианты нового механизма публикации, но все они по тем или иным параметрам не устраивали. Wiki не позволяла сделать версионирование и не имела наглядной структуры и оглавления. Confluence не имел внятной поддержки локализации кроме кошмарного варианта давайте сделаем отдельный спейс для каждой комбинации версия продукта + язык. Смотрели в сторону MadCap Flare, но в итоге отказались, решив, что нет никакой гарантии, что впоследствии не вылезут какие-то проблемы, которые снова заставят переезжать. В итоге выбор пал на Docs as Code как на вариант, обещавший в перспективе удовлетворить всем нашим требованиям.

Акт 2: Практика

Внедряем Docs as Code

Что же, вы решили внедрить в своей организации подход Docs as code. С чего начать?

Сформируйте список требований

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

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

Планируйте

Прежде чем начинать работу по внедрению, тщательно спланируйте ваш проект, разберитесь в существующих технологиях и инструментах. Эта грабля нам довольно больно стукнула по лбу. Мы начинали внедрение Docs as code силами отдела технической документации. Когда стало ясно, что нам не хватает где-то ресурсов, а где-то экспертизы, пришлось обратиться за помощью к коллегам. Мы обсудили с ними цели и план работ и пришли к выводу, что некоторые из выбранных инструментов лучше заменить. В итоге часть уже проделанной работы оказалась на свалке.

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

Пользоваться таким чудом может быть неудобно, а в худшем случае и вовсе невозможно.

Документируйте

Не ленитесь документировать вашу систему Docs as Code. Особенно если вы делаете что-то более сложное, чем один репозиторий Git + генератор статических сайтов в стандартной комплектации. Да, на это всегда не хватает времени, но поверьте, усилия окупятся сторицей. Через пару лет вам не нужно будет морщить лоб, пытаясь разобраться, как же оно тут все устроено. Это что? Как оно работает? Кто писал этот код? Ах, человек уже год как уволился... Чем подробнее вы опишете детали реализации вашего решения, тем проще его потом будет поддерживать и модернизировать. Если вы решили заказать создание системы Docs as Code на стороне, обязательно включите ее документирование в список задач, необходимых для выполнения.

Решите, в каком формате вы хотите публиковать документацию

HTML? PDF? DOC? Все из вышеперечисленного? В зависимости от ответа на этот вопрос вам может лучше подойти тот или иной язык разметки. Например, из reStructuredText можно публиковаться во все три вышеприведенных формата, а классическая интерпретация Markdown конвертируется только в HTML.

Выберите язык разметки

Зная задачу, проще подобрать инструмент для ее выполнения. Существует целый ряд легковесных языков разметки, но два самых популярных из них - reStructuredText и Markdown:

Markdown

Из двух рассматриваемых языков разметки этот более простой, но и более ограниченный в плане форматов, в которые он может быть сконвертирован без дополнительных приседаний. Существует несколько имплементаций Markdown, ни одна из которых не является канонической. Например, GitHub Flavored Markdown обладает более широкими возможностями по сравнению со своим предком. Выбрав наиболее подходящую для ваших нужд имплементацию Markdown, убедитесь, что используемый вами парсер корректно превращает ее в HTML.

reStructuredText

Более мощный язык разметки, но и более капризный. В нем сложнее писать и проще допустить ошибку в синтаксисе (во всяком случае, пока не привыкнешь). Например, чтобы документ в reStructuredText не собрался корректно, достаточно пропустить или поставить лишний пробел или перенос строки. Большое преимущество reStructuredText в его расширяемости при помощи плагинов вы можете научить систему публикации распознавать и корректно отображать необходимые вам сущности (ссылки, таблички, вставки и так далее) в HTML.

Пример из недавнего нам нужно было добавить возможность вставлять выделенный рамкой текст. Мы используем такое выделение для краткого описания содержания статей документации. Так пользователь может за несколько секунд понять, в нужную ли статью он зашел. Изначально подобного функционала у нас не было. Но за несколько часов у нас появилась возможность добавлять подобные вставки при помощи такого форматирования:

.. admonition:: summary

Hello world!

Собираем HTML и видим вот такое:

Какой язык разметки используется в Plesk? Мы подумали и решили:

Это не шутка мы действительно используем на нашем портале документации и reStructuredText и Markdown. Зачем? Все просто: мы используем разные языки разметки для решения разных задач с разными требованиями:

• reStructuredText используется для написания документации. Для этой задачи нам в первую очередь важны богатые возможности форматирования, а также расширяемость.

• Markdown используется для написания release notes. Мы пишем их много и часто, а требования к форматированию минимальны - болд/италик/моноспейс/кодблок/ссылки. Для этой задачи нам важнее всего простота и скорость использования.

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

Выберите инструмент для публикации

Вы определились с языком разметки. Пора выбрать инструмент, при помощи которого вы будете документацию публиковать. Вариантов несколько, но в этой статье для начинающих я хотел бы сфокусировать внимание на четырех: Hugo, Jekyll, Sphinx и MkDocs. По сути, все они являются генераторами статических сайтов. Hugo и Jekyll больше ориентированы на блоги, а Sphinx и MkDocs специально заточены для создания документации и обладают большим количеством полезных в этом деле фич из коробки. Все четыре инструмента популярны, широко используются, поддерживаются и имеют активное комьюнити.

Если выбор вас пугает, не переживайте. На самом деле, часть опций вы отсекли еще на предыдущих шагах. Генераторы статических сайтов поддерживают, как правило, один-два языка разметки. Если на предыдущем шаге вы выбрали reStructuredText (расширяемость наш выбор, а синтаксис выучим), то ваш главный кандидат Sphinx. И ваш выбор инструментов будет куда шире, если вы проголосовали за Markdown (мы не хотим возиться с reStructuredText и разбираться, почему после трех коммитов, призванных исправить ошибки форматирования, HTML собирается вкривь и вкось).

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

В Plesk для сборки документации мы используем Sphinx, а для сайта портала документации целиком - Jekyll. Это позволяет расцепить механизмы обновления непосредственно руководств и других страниц, размещенных на портале документации, например, чейнджлога или FAQ. Благодаря этому публикация release notes для новых версий продукта и его расширений занимает меньше минуты.

Сделайте красиво

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

Что насчет существующего контента?

Возможно, у вас уже есть сайт с документацией. Что же, при выборе Docs as code вам придется выбросить его или заново набивать руками? Не обязательно. Существуют решения для конвертации текстов из одного формата в другой, но с ними тоже придется разбираться. Как тут поступить зависит от объема существующей документации. Если у вас есть десяток-другой документов, возможно, будет проще, скрепя сердце, набрать их заново в выбранном языке разметки. В Plesk массив документации насчитывал приблизительно четыре с половиной тысячи документов, поэтому для нас подобный вариант не был реалистичным. В итоге мы без потерь сконвертировали всю существующая документацию из .html в .rst при помощи инструмента Pandoc.

Определитесь с версионированием

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

Дешевое решение паковать собранную документацию для старых версий продукта в архивы и делать их доступными для скачивания. Мы так поступаем с документацией для ушедших в EOL много лет назад версий Plesk, которыми уже почти никто не пользуется. Но это неудобно для пользователя. Клиент на старой версии продукта вряд ли сможет найти вашу документацию при помощи Google или другой поисковой системы (для справки: на docs.plesk.com органический поисковый трафик составляет более половины посетителей).

Нам было важно дать клиентам доступ к документации последней и предпоследней версий Plesk (Onyx и Obsidian) и сделать так, чтобы отдельная страница со своим контентом и URL была у обеих версий. Мы реализовали это следующим образом: в каждом репозитории Git, содержащем исходники того или иного руководства, есть несколько веток. Каждая ветка содержит исходные файлы для той или иной версии продукта, что позволяет вносить изменения в документацию, например, для Plesk Obsidian, при этом никак не затрагивая документацию для Plesk Onyx. Есть и недостаток: когда нужно обновить документацию для всех версий продукта сразу, приходится делать коммиты в каждую ветку по очереди, что тоже занимает время.

Ду ю спик инглиш?

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

Самый простой в реализации вариант создать отдельную ветку или репозиторий, сделать в нем копию исходников на языке, на котором вы пишете, а затем в этой же ветке или репозитории переводить. И так для каждого языка, отличного от исходного. На практике такой подход вряд ли практичен он требует от переводчиков навыков работы с Git и знания синтаксиса .rst. К тому же, если вы планируете работать со сторонними переводчиками, нужно будет внимательно настроить им права доступа, чтобы они не могли видеть, например, исходный код продукта. Вдобавок, это создаст постоянную головную боль процессного плана: обновили документацию нужно дать знать переводчикам, что они должны отразить изменения и в своих исходниках.

Мы пошли более затратным в реализации, но куда более дешевым в использовании путем. Мы разбиваем исходные документы на английском языке на единицы перевода (заголовки, абзацы все, что с обеих сторон ограничено переносом строки). Переводы руководств на все языки хранятся в том же репозитории/ветке, что и само руководство в виде .po файлов. Содержимое их выглядит так:

#: ../../../../projects/administrator-guide/source/53231.rst:15

msgid "You can choose to:"

msgstr "Folgende Optionen stehen zur Verfgung:"

Здесь мы видим перевод единицы перевода из репозитория administrator-guide, документ 53231.rst, строка 15. В наличии как исходная строка, так и ее перевод на немецкий (всего в данном .po файле шесть таких единиц, некоторые поменьше, некоторые побольше). В итоге все содержимое документа на английском покрывается переводом. При сборке документации на немецком механизм берет исходный файл .rst и автоматически заменяет единицы перевода в нем на переведенные. Данный подход позволил нам интегрироваться с сервисом Crowdin, в котором работают наши переводчики. Они пользуются привычным им интерфейсом мы получаем переводы.

Автоматизируй это

Одно из основных преимуществ подхода Docs as code - возможность использовать инструменты непрерывного развертывания, чтобы передать связанные с публикацией рутинные операции на попечение роботов. Не пренебрегайте им. Чем чаще вы вносите изменения или публикуете новые документы, тем больше времени автоматика вам сэкономит. С тех пор, как мы внедрили автоматическую публикацию по слиянию, автоматика экономит нам минимум один-два (а зачастую и больше) человеко-часа каждую неделю, а также исключает подобные драматические сцены:

-Василий, почему релиз ноты еще не на продакшене? Два часа как вышло обновление, клиенты жалуются (у нас были подобные случаи и клиенты действительно жалуются)!

-А, черт, я закоммитил, а запустить сборку забыл :(

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

1. При слиянии ветки с изменениями в основную, сервер Jenkins запускает сборку гайда, в который были внесены изменения (.rst => .html), на всех языках, на которые он переведен, а также обновляет файлы .po, которые пойдут потом на перевод. Если мы публикуем релиз ноты, этот шаг пропускается.

2. Пересобирается сам портал документации, включая релиз ноты, FAQ и все прочие находящиеся на нем страницы.

3. Собранная документация разворачивается на сервере.

4. Сети доставки содержимого подается команда сбросить кэш.

Здесь есть еще одна тонкость. Кроме Plesk, мы публикуем множество расширений к нему, и каждый новый выпуск каждого из расширений тоже сопровождается своими релиз нотами. Они становятся доступными к сборке документации как только попадают в основную ветвь, поскольку для них время публикации не особо критично. Но для обновлений самого Plesk релиз ноты должны появиться в публичном доступе одновременно с выходом обновления, иначе сразу начинают сыпаться запросы от клиентов ("Мой Plesk автоматически обновился, где я могу прочесть об изменениях?", "Я вижу на портале документации релиз ноты для обновления Plesk, как мне его поставить?"). Во избежание подобных ситуаций, релиз ноты для основного продукта становятся доступными к сборке документации и публикуются строго в рамках публикации обновления Plesk.

Заключение

Нужен ли вам Docs as code? Зависит от. Если у вас небольшая компания, несложный продукт, устоявшиеся процессы и дюжина страниц документации, которые вы обновляете раз в квартал пожалуй, выхлоп не окупит затрат на внедрение. Если же вас заинтересовали описанные в моей статье возможности, или вы просто любите быть на острие прогресса почему нет? Просто заранее вдумчиво спланируйте вашу будущую систему Docs as code исходя из ваших уникальных потребностей, и я уверен вы не пожалеете :)

Спасибо за внимание!

P.S. Хочу также сказать "спасибо" Николаю Волынкину, Дмитрию Ширяеву и Катерине Говердовской за участие в работе по созданию и наполнению нашего портала документации, а также за помощь в написании статьи.

Новая порция инсайтов, мероприятий, книжек и шпаргалок. Оставайтесь с нами станьте частью DevNation!

Узнать новое:

• Anacron для более удобной работы с crontab
  Вместо того, чтобы вручную выполнять повторяющиеся задачи, позвольте Linux сделать все за Вас

• Гайд по команде git stash
  Узнайте, когда и как пользоваться командой git stash

• Быстрая конфигурация SD-карт для кластера Raspberry Pi
  Создавайте несколько SD-карт, которые сконфигурированы для кластеров Pi с помощью Cloudmesh Pi Burner.

• 3 причины использовать команду Git cherry-pick

• DevOps-руководство по документации

• 20 способов стать продуктивным и начать уважать себя

• Как разделить диск на разделы под Linux с помощью GNU Parted

Скачать:

• Шпаргалка по SQLite
  Держите под рукой полезный список распространенных команд SQLite

Почитать на досуге:

• Электронная книга: Переход на .NET Core на Red Hat Enterprise Linux
  Здесь уже скачана на Google Drive

• Безопасность в числе главных приоритетов при поддержке исследований в IT

• Бесплатный онлайн-курс: "Разработка облачных приложений с микросервисной архитектурой"

• Понять разработчика: иллюстрированное руководство по графикам

• 7 вопросов для собеседования на позицию Site Reliability Engineer (SRE)

• 5 малоизученных, но полезных команд Linux для сисадминов

Мероприятия:

• Виртуальный Red Hat Summit 2021, 27-28 апреля
  Бесплатная онлайн-конференция Red Hat Summit это отличный способ узнать последние новости ИТ-индустрии, задать свои вопросы техническим экспертам, услышать истории успеха непосредственно от заказчиков Red Hat и увидеть, как открытый код генерирует инновации в корпоративном секторе.

• Cook Your Own Cloud: OpenShift + OpenStack + немного перца! 30 апреля
  Миграция на облачную платформу тем актуальнее, чем сложнее инфраструктура и выше число изменений. Как насчет того, чтобы автоматизировать рутинные задачи и сконцентрироваться на бизнес-процессах? Мы в Red Hat знаем, как создать облачное решение для IaaS и PaaS- платформ. И мы хотим поделиться своим опытом! На вебинаре архитектор Дмитрий Алехин расскажет про связку Red Hat Openstack Platform и Red Hat Openshift Container Platform, которые позволяют осуществить стратегию открытого гибридного облака. Регистрируйтесь и приходите!

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

Узнать новое:

• 6 советов по защите Linux-сервера для начинающих
  Воспользуетесь ими, чтобы сделать свою среду Linux более безопасной.

• Играем в прикольную арифметическую игру с помощью команд Linux
  Почему бы не устроить британское телевикторину Countdown у себя дома?

• 4 способа переключения контекста в Git
  Сравниваем плюсы и минусы четырех подходов к смене бранчей в Git.

• 5 причин, по которым сисадмин должен любить systemd

• Как зариповать и каталогизировать свои аудио-CD с помощью опенсорсных инструментов

• Как сбрасывать сканы документов на Linux-машину по сети

• Балансировка нагрузки, руководство для начинающих

Скачать:

• Шпаргалка по Linux-командам для работы сетями
  Основные команды и что можно узнать с их помощью.

• Шпаргалка по GNU Screen
  В GNU Screen есть море клавиатурных команд. Часто используемые запоминаются легко, а вот за остальными приходится обращаться к экрану справки. Или их можно распечатать и держать под рукой.

Что еще интересного:

• Бесплатный онлайн-курс Основы Ansible

• Шпаргалка по Linux-командам для работы с текстом, дисками, сетями и учетными записями

• Бесплатная запись Red Hat Summit 2021

• 5 аппаратных архитектур для машинного обучения на edge-системах

• 5 признаков, что вам надо поработать над эмоциональным интеллектом

• Домашняя автоматизация: запускаем Home Assistant через Podman

Мероприятия:

• 6 мая. DevNation: The Show

Вебинары:

• 13 мая. Вебинар про бессерверные технологии в OpenShift
  Мы начинаем серию вебинаров, посвященных OpenShift'у и его окружению.

  Первый вебинар в серии про бессерверные технологии.

• 20 мая. Вебинар OpenShift Virtualization: Виртуальные машины, контейнеры и serverless вместе, в идеальном порядке
  Третий вебинар в серии про OpenShift Virtualization

Системы Skyscanner сложно назвать маломасштабными. Наш сайт и приложение каждый месяц используются миллионами путешественников, мы обрабатываем умопомрачительные объёмы запросов, используя микросервисную архитектуру, которая сама по себе далеко не маленькая.В общей совокупности у нас задействовано несколько сотен микросервисов и микросайтов (веб-приложений, поддерживающих определённую часть нашего сайта), обслуживаемых сотнями экземпляров AWS Lambda и библиотек. Каждое из этих средств хранится в своём собственном репозитории GitHub, что даёт некоторые преимущества с точки зрения разделения задач, но имеет и свою цену: когда одно и то же изменение нужно выполнить во всех этих репозиториях, как это можно осуществить?

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

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

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

Долгое время мы разрабатывали свою внутреннюю систему под названием Codelift. В первую очередь это была система пакетной обработки, которая в ночное время применяла написанный на Python сценарий изменения для каждого из сотен репозиториев, отправляя предложения на изменения кода в чужих репозиториях (PR-предложения) для всех таких изменений. Но, как оказалось, очень сложно написать такой сценарий, который бы надёжно отрабатывал со всеми репозиториями. Главным узким местом была потребность в квалифицированных специалистах, которые требовались для проверки этих сценариев изменений. И самим сценариям часто требовалось несколько раундов настройки, чтобы преодолеть неизбежные сбои. Система Codelift постепенно выводилась из эксплуатации, но потребность в ней оставалась.

Появление Turbolift

Система Turbolift это переосмысление процесса внесения массовых изменений.

• Прежде, чтобы написать надёжно работающий сценарий внесения изменения в системе Codelift, инженерам приходилось создавать локальные копии (клоны) многих или даже всех задействованных репозиториев только для проверки работоспособности этого изменения. Но если инженеры в любом случае собираются создавать локальные копии репозиториев, почему не сделать это частью процесса?

• Подготовка сценариев изменений на Python накладывала свои ограничения: иногда самым простым способом реализации изменения является просто вызов команды из оболочки или запуск более специализированного инструмента рефакторинга, такого как codemod или comby. Иногда предпочтителен вызов редактора или интегрированной среды разработки это будет хоть и тяжеловесным, но самым верным способом. А иногда самым простым вариантом выполнения будет автоматическое изменение, которое сработает для 95 % репозиториев с последующей ручной настройкой для нескольких репозиториев, где такая настройка потребуется.

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

• Одной из тонких проблем с Codelift было то, что все его PR-предложения исходили от пользователя-бота: при этом от владельцев системы Codelift ожидалась тщательная проверка каждого изменения, и это становилось серьёзным узким местом. Мы поняли, что оптимальным будет создание предложений на изменения кода в чужих репозиториях инженером, который фактически несёт ответственность за их выполнение. В этом случае обеспечиваются прозрачность распределения прав, более простая обратная связь и отсутствие необходимости создавать целую команду посредников.

Система Turbolift автоматизирует наиболее утомительные этапы этого процесса: массовое распараллеливание альтернативных вариантов выполнения процесса, клонирование, создание PR-предложенийбез внесения каких-либо противоречий при выполнении самих фактических изменений. Инженеры могут непосредственно проверять, изменять и тестировать свои изменения, используя те инструменты, которые им требуются, что позволяет работать с гораздо большей степенью отдачи, чем просто отправить сценарий в систему пакетной обработки и ожидать результатов.

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

Система Turbolift начинала жизнь как наскоро написанный набор bash-сценариев, но она быстро доказала нам свою полезность. Теперь, когда мы переписали эту систему на Go, привели в порядок и сделали её инструментом с открытым исходным кодом, хотелось бы поделиться ею с вами. По сравнению с первоначальной версией язык Go помог сделать этот инструмент более удобным для использования и обслуживании в долгосрочной перспективе. У нас есть множество идей о дальнейшем развитии этого инструмента, и мы приветствуем все поступающие от вас предложения о том, как улучшить его.

Если вы начнёте работать с Turbolift, советуем вам уделить особое внимание потребностям инженеров, анализирующих предложения на изменения кода в чужих репозиториях, особенно, если создаётся много таких PR-предложений. В файле README для этого проекта содержится несколько рекомендаций, которые мы разработали внутрикорпоративно, чтобы помочь авторам изменений, удерживая их в рамках разумного.

Как инструмент Turbolift помог нам

• При приближении момента, когда истечёт срок действия какого-либо внутреннего SSL-сертификата, наша команда сопровождения промышленной платформы использовала Turbolift для выполнения PR-предложений сотен репозиториев, в которых были ссылки на истекающий сертификат.

• Turbolift применяется нашей командой веб-поддержки для стандартизации версий и тестирования библиотек на наших микросайтах.

• Наша команда сопровождения промышленной платформы использовала Turbolift для исправления ошибки, которую когда-то допустили в шаблоне кода, а затем растиражировали по множествам репозиториев.

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

В целом за последние три месяца, используя Turbolift, мы отправили свыше 1200 внутренних предложений на изменения кода в чужих репозиториях. Каждый из этих случаев означает устранённую проблему или исправленную техническую недоработку, которые в противном случае превратились бы в создаваемые вручную PR-предложения. Мы надеемся, что инженеры в Skyscanner и других компаниях в полной мере ощутят преимущества от упрощения рабочего процесса при выполнении масштабных изменений.

Turbolift написан на Go компилируемом языке от Google, который вы за год освоите с нуля на курсе Backend-разработчик на Go от ключевых понятий в IT, основ Linux и до применения Go для DevOps. Мы используем модель фундаментального образования, поэтому вы получите не только практические навыки, но и крепкую теоретическую базу, научитесь мыслить по-новому и в этом вам помогут эксперты в своём деле и менторы, которые с удовольствием ответят на ваши вопросы и передадут вам свои знания.

Узнайте, как прокачаться и в других специальностях или освоить их с нуля:

• Профессия Data Scientist

• Профессия Data Analyst

• Курс по Data Engineering

Отыщи всему начало, и ты многое поймёшь (Козьма Прутков).

Меня зовут Руслан, я релиз-инженер в Badoo и Bumble. Недавно я столкнулся с необходимостью оптимизировать механизм автомерджа в мобильных проектах. Задача оказалась интересной, поэтому я решил поделиться её решением с вами. В статье я расскажу, как у нас раньше было реализовано автоматическое слияние веток Git и как потом мы увеличили пропускную способность автомерджа и сохранили надёжность процессов на прежнем высоком уровне.

Свой автомердж

Многие программисты ежедневно запускают git merge, разрешают конфликты и проверяют свои действия тестами. Кто-то автоматизирует сборки, чтобы они запускались автоматически на отдельном сервере. Но решать, какие ветки сливать, всё равно приходится человеку. Кто-то идёт дальше и добавляет автоматическое слияние изменений, получая систему непрерывной интеграции (Continuous Integration, или CI).

Например, GitHub предлагает полуручной режим, при котором пользователь с правом делать записи в репозиторий может поставить флажок Allow auto-merge (Разрешить автомердж). При соблюдении условий, заданных в настройках, ветка будет соединена с целевой веткой. Bitbucket поддерживает большую степень автоматизации, накладывая при этом существенные ограничения на модель ветвления, имена веток и на количество мерджей.

Такой автоматизации может быть достаточно для небольших проектов. Но с увеличением количества разработчиков и веток, ограничения, накладываемые сервисами, могут существенно повлиять на производительность CI. Например, раньше у нас была система мерджа, при которой основная ветка всегда находилась в стабильном состоянии благодаря последовательной стратегии слияний. Обязательным условием слияния была успешная сборка при наличии всех коммитов основной ветки в ветке разработчика. Работает эта стратегия надёжно, но у неё есть предел, определяемый временем сборки. И этого предела оказалось недостаточно. При времени сборки в 30 минут на обработку 100 слияний в день потребовалось бы более двух суток. Чтобы исключить ограничения подобного рода и получить максимальную свободу выбора стратегий мерджа и моделей ветвления, мы создали собственный автомердж.

Итак, у нас есть свой автомердж, который мы адаптируем под нужды каждой команды. Давайте рассмотрим реализацию одной из наиболее интересных схем, которую используют наши команды Android и iOS.

Термины

Main. Так я буду ссылаться на основную ветку репозитория Git. И коротко, и безопасно. =)

Сборка. Под этим будем иметь в виду сборку в TeamCity, ассоциированную с веткой Git и тикетом в трекере Jira. В ней выполняются как минимум статический анализ, компиляция и тестирование. Удачная сборка на последней ревизии ветки в сочетании со статусом тикета To Merge это однo из необходимых условий автомерджа.

Пример модели ветвления

Испробовав разные модели ветвления в мобильных проектах, мы пришли к следующему упрощённому варианту:

На основе ветки main разработчик создаёт ветку с названием, включающим идентификатор тикета в трекере, например PRJ-k. По завершении работы над тикетом разработчик переводит его в статус Resolved. При помощи хуков, встроенных в трекер, мы запускаем для ветки тикета сборку. В определённый момент, когда изменения прошли ревью и необходимые проверки автотестами на разных уровнях, тикет получает статус To Merge, его забирает автоматика и отправляет в main.

Раз в неделю на основе main мы создаём ветку релиза release_x.y.z, запускаем на ней финальные сборки, при необходимости исправляем ошибки и наконец выкладываем результат сборки релиза в App Store или Google Play. Все фазы веток отражаются в статусах и дополнительных полях тикетов Jira. В общении с Jira помогает наш клиент REST API.

Такая простая модель не только позволила нам построить надёжный автомердж, но и оказалась удобной для всех участников процесса. Однако сама реализация автомерджа менялась несколько раз, прежде чем мы добились высокой производительности и минимизировали количество побочных эффектов: конфликтов, переоткрытий тикетов и ненужных пересборок.

Первая версия: жадная стратегия

Сначала мы шли от простого и очевидного. Брали все тикеты, находящиеся в статусе To Merge, выбирали из них те, для которых есть успешные сборки, и отправляли их в main командой git merge, по одной.

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

Наличие в TeamCity актуальной успешной сборки мы проверяли при помощи метода REST API getAllBuilds примерно следующим образом (псевдокод):

haveFailed = False # Есть ли неудачные сборкиhaveActive = False # Есть ли активные сборки# Получаем сборки типа buildType для коммита commit ветки branchbuilds = teamCity.getAllBuilds(buildType, branch, commit)# Проверяем каждую сборкуfor build in builds:  # Проверяем каждую ревизию в сборке  for revision in build.revisions:    if revision.branch is branch and revision.commit is commit:      # Сборка актуальна      if build.isSuccessful:        # Сборка актуальна и успешна        return True      else if build.isRunning or build.isQueued        haveActive = True      else if build.isFailed:        haveFailed = Trueif haveFailed:  # Исключаем тикет из очереди, переоткрывая его  ticket = Jira.getTicket(branch.ticketKey)  ticket.reopen("Build Failed")  return Falseif not haveActiveBuilds:  # Нет ни активных, ни упавших, ни удачных сборок. Запускаем новую  TriggerBuild(buildType, branch)

Ревизии это коммиты, на основе которых TeamCity выполняет сборку. Они отображаются в виде 16-ричных последовательностей на вкладке Changes (Изменения) страницы сборки в веб-интерфейсе TeamCity. Благодаря ревизиям мы можем легко определить, требуется ли пересборка ветки тикета или тикет готов к слиянию.

Важно, что ревизию можно (а часто даже необходимо) указывать в запросе на добавление новой сборки в очередь в параметре lastChanges, потому что в противном случае TeamCity может выбрать устаревшую ревизию ветки при запуске сборки. Как будет показано ниже, указывать ревизию необходимо в тех случаях, если, например, логика вне TeamCity основана на поиске сборок на конкретных коммитах (наш случай).

Так как после перевода тикета в статус готовности (в нашем примере Resolved) соответствующая ветка, как правило, не меняется, то и сборка, ассоциированная с тикетом, чаще всего остаётся актуальной. Кроме того, сам факт нахождения тикета в статусе To Merge говорит о высокой вероятности того, что сборка не упала. Ведь при падении сборки мы сразу переоткрываем тикет.

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

Всё работало быстро, но требовало внимания. То и дело возникали ситуации, когда изменения нескольких тикетов конфликтовали между собой. Конфликты при слияниях как явление достаточно распространённое поначалу ни у кого особых вопросов не вызывали. Их разрешали разработчики, дежурные по релизу. Но с увеличением количества разработчиков, задач и, соответственно, веток, приведение релиза в порядок требовало всё больше усилий. Задержки в разрешении конфликтов начали сказываться на новых задачах. Полагаю, не стоит продолжать эту цепочку скорее всего, вы уже поняли, что я имею в виду. С конфликтами нужно было что-то делать, причём не допуская их попадания в релиз.

Конфликты слияния

Если изменить одну и ту же строку кода в разных ветках и попытаться соединить их в main, то Git попросит разрешить конфликты слияния. Из двух вариантов нужно выбрать один и закоммитить изменения.

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

Если команда git merge завершилась с ошибкой и для всех файлов в списке git ls-files --unmerged заданы обработчики конфликтов, то для каждого такого файла мы выполняем парсинг содержимого по маркерам конфликтов <<<<<<<, ======= и >>>>>>>. Если конфликты вызваны только изменением версии приложения, то, например, выбираем последнюю версию между локальной и удалённой частями конфликта.

Конфликт слияния это один из простейших типов конфликтов в CI. При конфликте с main CI обязан уведомить разработчика о проблеме, а также исключить ветку из следующих циклов автомерджа до тех пор, пока в ней не появятся новые коммиты.

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

Логические конфликты

А может ли случиться так, что, несмотря на успешность сборок пары веток в отдельности, после слияния их с main сборка на основной ветке упадёт? Практика показывает, что может. Например, если сумма a и b в каждой из двух веток не превышает 5, то это не гарантирует того, что совокупные изменения a и b в этих ветках не приведут к большей сумме.

Попробуем воспроизвести это на примере Bash-скрипта test.sh:

#!/bin/bashget_a() {    printf '%d\n' 1}get_b() {    printf '%d\n' 2}check_limit() {    local -i value="$1"    local -i limit="$2"    if (( value > limit )); then        printf >&2 '%d > %d%s\n' "$value" "$limit"        exit 1    fi}limit=5a=$(get_a)b=$(get_b)sum=$(( a + b ))check_limit "$a" "$limit"check_limit "$b" "$limit"check_limit "$sum" "$limit"printf 'OK\n'

Закоммитим его и создадим пару веток: a и b.
Пусть в первой ветке функция get_a() вернёт 3, а во второй get_b() вернёт 4:

diff --git a/test.sh b/test.shindex f118d07..39d3b53 100644--- a/test.sh+++ b/test.sh@@ -1,7 +1,7 @@ #!/bin/bash get_a() {-    printf '%d\n' 1+    printf '%d\n' 3 } get_b() {git diff main bdiff --git a/test.sh b/test.shindex f118d07..0bd80bb 100644--- a/test.sh+++ b/test.sh@@ -5,7 +5,7 @@ get_a() { }  get_b() {-    printf '%d\n' 2+    printf '%d\n' 4 }  check_limit() {

В обоих случаях сумма не превышает 5 и наш тест проходит успешно:

git checkout a && bash test.shSwitched to branch 'a'OKgit checkout b && bash test.shSwitched to branch 'b'OK

Но после слияния main с ветками тесты перестают проходить, несмотря на отсутствие явных конфликтов:

git merge a bFast-forwarding to: aTrying simple merge with bSimple merge did not work, trying automatic merge.Auto-merging test.shMerge made by the 'octopus' strategy. test.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)bash test.sh7 > 5

Было бы проще, если бы вместо get_a() и get_b() использовались присваивания: a=1; b=2, заметит внимательный читатель и будет прав. Да, так было бы проще. Но, вероятно, именно поэтому встроенный алгоритм автомерджа Git успешно обнаружил бы конфликтную ситуацию (что не позволило бы продемонстрировать проблему логического конфликта):

git merge a Updating 4d4f90e..8b55df0Fast-forward test.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)git merge b Auto-merging test.shCONFLICT (content): Merge conflict in test.shRecorded preimage for 'test.sh'Automatic merge failed; fix conflicts and then commit the result.

Разумеется, на практике конфликты бывают менее явными. Например, разные ветки могут полагаться на API разных версий какой-нибудь библиотеки зависимости, притом что более новая версия не поддерживает обратной совместимости. Без глубоких знаний кодовой базы (читай: без разработчиков проекта) обойтись вряд ли получится. Но ведь CI как раз и нужен для решения таких проблем.

Конечно, от разрешения конфликта мы никуда не уйдём кто-то должен внести правки. Но чем раньше нам удастся обнаружить проблему, тем меньше людей будет привлечено к её решению. В идеале потребуется озадачить лишь разработчика одной из конфликтующих веток. Если таких веток две, то одна из них вполне может быть соединена с main.

Превентивные меры

Итак, главное не допустить попадания логического конфликта в main. Иначе придётся долго и мучительно искать источник ошибок, а затем программиста, который проблему должен или может решить. Причём делать это нужно максимально быстро и качественно, чтобы, во-первых, не допустить задержки релиза и во-вторых, избежать в новых ветках логических конфликтов, основанных на уже выявленном конфликте. Такие конфликты часто приводят к неработоспособности большой части приложения или вовсе блокируют его запуск.

Нужно синхронизировать ветки так, чтобы их совокупный вклад в main не приводил к падению сборки релиза. Ясно, что все готовые к слиянию ветки нужно так или иначе объединить и прогнать тесты по результату объединения. Путей решения много, давайте посмотрим, каким был наш путь.

Вторая версия: последовательная стратегия

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

Git, по идее, как раз и является средством синхронизации. Но порядок попадания веток в main и, наоборот, main в ветки определяем мы сами. Чтобы определить точно, какие из веток вызывают проблемы в main, можно попробовать отправлять их туда по одной. Тогда можно выстроить их в очередь, а порядок организовать на основе времени попадания тикета в статус To Merge в стиле первый пришёл первым обслужен.

С порядком определились. А как дальше соединять ветки? Допустим, мы сольём в main первый тикет из очереди. Так как main изменилась, она может конфликтовать с остальными тикетами в очереди. Поэтому перед тем как сливать следующий тикет, нужно удостовериться, что обновлённая main по-прежнему совместима с ним. Для этого достаточно слить main в тикет. Но так как после соединения main с веткой её состояние отличается от того, которое было в сборке, необходимо перезапустить сборку. Для сохранения порядка все остальные тикеты в очереди должны ждать завершения сборки и обработки впередистоящих тикетов. Примерно такие рассуждения привели нас к последовательной стратегии автомерджа.

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

Но есть у этой схемы существенный недостаток: пропускная способность автомерджа линейно зависит от времени сборки. При среднем времени сборки iOS-приложения в 25 минут мы можем рассчитывать на прохождение максимум 57 тикетов в сутки. В случае же с Android-приложением требуется примерно 45 минут, что ограничивает автомердж 32 тикетами в сутки, а это даже меньше количества Android-разработчиков в нашей компании.

На практике время ожидания тикета в статусе To Merge составляло в среднем 2 часа 40 минут со всплесками, доходящими до 10 часов! Необходимость оптимизации стала очевидной. Нужно было увеличить скорость слияний, сохранив при этом стабильность последовательной стратегии.

Финальная версия: сочетание последовательной и жадной стратегий

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

Давайте вспомним идею жадной стратегии: мы сливали все ветки готовых тикетов в main. Основной проблемой было отсутствие синхронизации между ветками. Решив её, мы получим быстрый и надёжный автомердж!

Раз нужно оценить общий вклад всех тикетов в статусе To Merge в main, то почему бы не слить все ветки в некоторую промежуточную ветку Main Candidate (MC) и не запустить сборку на ней? Если сборка окажется успешной, то можно смело сливать MC в main. В противном случае придётся исключать часть тикетов из MC и запускать сборку заново.

Как понять, какие тикеты исключить? Допустим, у нас n тикетов. На практике причиной падения сборки чаще всего является один тикет. Где он находится, мы не знаем все позиции от 1 до n являются равноценными. Поэтому для поиска проблемного тикета мы делим n пополам.

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

Следуя этому алгоритму, для k проблемных тикетов в худшем случае нам придётся выполнить O(k*log2(n)) сборок, прежде чем мы обработаем все проблемные тикеты и получим удачную сборку на оставшихся.

Вероятность благоприятного исхода велика. А ещё в то время, пока сборки на ветке MC падают, мы можем продолжать работу при помощи последовательного алгоритма!

Итак, у нас есть две автономные модели автомерджа: последовательная (назовём её Sequential Merge, или SM) и жадная (назовём её Greedy Merge, или GM). Чтобы получить пользу от обеих, нужно дать им возможность работать параллельно. А параллельные процессы требуют синхронизации, которой можно добиться либо средствами межпроцессного взаимодействия, либо неблокирующей синхронизацией, либо сочетанием этих двух методов. Во всяком случае, мне другие методы неизвестны.

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

Остаётся предотвратить все возможные случаи состояний гонки. Их много, но для понимания сути приведу несколько самых важных:

1. SM-SM и GM-GM: между командами одного типа.

2. SM-GM: между SM и GM в рамках одного репозитория.

Первая проблема легко решается при помощи мьютекса по токену, включающему в себя имя команды и название репозитория. Пример: lock_${command}_${repository}.

Поясню, в чём заключается сложность второго случая. Если SM и GM будут действовать несогласованно, то может случиться так, что SM соединит main с первым тикетом из очереди, а GM этого тикета не заметит, то есть соберёт все остальные тикеты без учёта первого. Например, если SM переведёт тикет в статус In Master, а GM будет всегда выбирать тикеты по статусу To Merge, то GM может никогда не обработать тикета, соединённого SM. При этом тот самый первый тикет может конфликтовать как минимум с одним из других.

Во избежание логических конфликтов GM нужно обрабатывать все тикеты в очереди без исключения. По этой же причине алгоритм GM в связке с SM обязательно должен соблюдать тот же порядок тикетов в очереди, что и SM, так как именно этот порядок определяет, какая половина очереди будет выбрана в случае неудачной сборки в GM. При соблюдении этих условий тикет, обрабатываемый SM, будет всегда входить в сборку GM, что обеспечит нам нужную степень синхронизации.

Таким образом, мы получили своего рода неблокирующую синхронизацию.

Немного о TeamCity

В процессе реализации GM нам предстояло обработать много нюансов, которыми я не хочу перегружать статью. Но один из них заслуживает внимания. В ходе разработки я столкнулся с проблемой зацикливания команды GM: процесс постоянно пересобирал ветку MC и создавал новую сборку в TeamCity. Проблема оказалась в том, что TeamCity не успел скачать обновления репозитория, в которых была ветка MC, созданная процессом GM несколько секунд назад. К слову, интервал обновления репозитория в TeamCity у нас составляет примерно 30 секунд.

В качестве хотфикса я ввёл плавающий тег сборки, то есть создал в TeamCity тег с названием, похожим на automerge_ios_repo_git, и перемещал его от сборки к сборке, чтобы иметь представление о том, какая сборка является актуальной, в каком она состоянии и т. д. Но, понимая несовершенство этого подхода, я взялся за поиски способа донесения до TeamCity информации о новом состоянии ветки MC, а также способа прикрепления ревизии к сборке.

Кто-то посчитает решение очевидным, но я нашёл его не сразу. Оказывается, прикрепить ревизию к сборке при её добавлении в очередь можно при помощи параметра lastChanges метода addBuildToQueue:

<lastChanges>  <change    locator="version:{{revision}},buildType:(id:{{build_type}})"/></lastChanges>

В этом примере {{revision}} заменяется на 16-ричную последовательность коммита, а {{build_type}} на идентификатор конфигурации сборки. Но этого недостаточно, так как TeamCity, не имея информации о новом коммите, может отказать нам в запросе.

Для того чтобы новый коммит дошёл до TeamCity, нужно либо подождать примерно столько, сколько указано в настройках конфигурации корня VCS, либо попросить TeamCity проверить наличие изменений в репозитории (Pending Changes) при помощи метода requestPendingChangesCheck, а затем подождать, пока TeamCity скачает изменения, содержащие наш коммит. Проверка такого рода выполняется посредством метода getChange, где в changeLocator нужно передать как минимум сам коммит в качестве параметра локатора version. Кстати, на момент написания статьи (и кода) на странице ChangeLocator в официальной документации описание параметра version отсутствовало. Быть может, поэтому я не сразу узнал о его существовании и о том, что это 40-символьный 16-ричный хеш коммита.

Псевдокод:

teamCity.requestPendingChanges(buildType)attempt = 1while attempt <= 20:  response = teamCity.getChange(commit, buildType)  if response.commit == commit:    return True # Дождались  sleep(10)return False

О предельно высокой скорости слияний

У жадной стратегии есть недостаток на поиск ветки с ошибкой может потребоваться много времени. Например, 6 сборок для 20 тикетов у нас может занять около трёх часов. Можно ли устранить этот недостаток?

Допустим, в очереди находится 10 тикетов, среди которых только 6-й приводит к падению сборки.

Согласно жадной стратегии, мы пробуем собрать сразу все 10 тикетов, что приводит к падению сборки. Далее собираем левую половину (с 1 по 5) успешно, так как тикет с ошибкой остался в правой половине.

Если бы мы сразу запустили сборку на левой половине очереди, то не потеряли бы времени. А если бы проблемным оказался не 6-й тикет, а 4-й, то было бы выгодно запустить сборку на четверти длины всей очереди, то есть на тикетах с 1 по 3, например.

Продолжая эту мысль, мы придём к выводу о том, что полностью избавиться от ожиданий неудачных сборок можно только при условии параллельного запуска сборок всех комбинаций тикетов:

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

Примерно такой же алгоритм реализован в премиум-функции GitLab под названием Merge Trains. Перевода этого названия на русский язык я не нашёл, поэтому назову его Поезда слияний. Поезд представляет собой очередь запросов на слияние с основной веткой (merge requests). Для каждого такого запроса выполняется слияние изменений ветки самого запроса с изменениями всех запросов, расположенных перед ним (то есть запросов, добавленных в поезд ранее). Например, для трёх запросов на слияние A, B и С GitLab создаёт следующие сборки:

1. Изменения из А, соединённые с основной веткой.

2. Изменения из A и B, соединённые с основной веткой.

3. Изменения из A, B и C, соединённые с основной веткой.

Если сборка падает, то соответствующий запрос из очереди удаляется, а сборки всех предыдущих запросов перезапускаются (без учёта удалённого запроса).

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

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

Но если преград человеческой мысли нет, то пределы аппаратных ресурсов видны достаточно отчётливо:

1. Каждой сборке нужен свой агент в TeamCity.

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

3. Сборки автомерджа мобильных приложений в main составляют лишь малую часть от общего количества сборок в TeamCity.

Взвесив все плюсы и минусы, мы решили пока остановиться на алгоритме SM + GM. При текущей скорости роста очереди тикетов алгоритм показывает хорошие результаты. Если в будущем заметим возможные проблемы с пропускной способностью, то, вероятно, пойдём в сторону Merge Trains и добавим пару параллельных сборок GM:

1. Вся очередь.

2. Левая половина очереди.

3. Левая четверть очереди.

Что в итоге получилось

В результате применения комбинированной стратегии автомерджа нам удалось добиться следующего:

• уменьшение среднего размера очереди в 2-3 раза;

• уменьшение среднего времени ожидания в 4-5 раз;

• мердж порядка 50 веток в день в каждом из упомянутых проектов;

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

Примеры графиков слияний за несколько дней:

Количество тикетов в очереди до и после внедрения нового алгоритма:

Среднее количество тикетов в очереди (AVG) уменьшилось в 2,5 раза (3,95/1,55).

Время ожидания тикетов в минутах:

Среднее время ожидания (AVG) уменьшилось в 4,4 раза (155,5/35,07).

Опасное это дело, Фродо, выходить за порог: стоит ступить на дорогу и, если дашь волю ногам, неизвестно куда тебя занесет.

(с) Властелин Колец: Братство Кольца

С чего всё началось

Мне захотелось завести себе домашний Git-сервер, чтобы практиковаться в разработке и развёртывании пет-проектов. Плюс спокойнее, когда твои наработки лежат не только на github.

В качестве операционной системы выбрал Alpine linux, так как меня заинтересовали её возможности. Был опыт размещения на ней небольшого сервиса. Понравилось, что в ней нет ничего лишнего, а ещё она очень лёгкая в плане системных ресурсов.

Исходные данные

В распоряжении был гипервизор на Proxmox 6.1-3, контейнер с системой Alpine просто взял из шаблонов (template) - Alpine Linux 3.12 Kernel 5.3.10-1-pve on an x86_64.

Реализацию Git-сервера выбирал из числа открытых и бесплатных проектов. Решил взять для начала, тот у которого меньше настроек и лишних плюшек. Мне нужен git-сервер, который не требователен к ресурсам и наличием базовых операций. Остановился на проекте Gogs.io.

Причины такого выбора:

1. знакомый интерфейс, т.к. использую на работе;

2. написан на Golang - значит довольно шустрый;

3. минимальный набор настроек и функционала;

4. нормальная документация.

Мой гипервизор пока обладает скромным железом. В распоряжении только:

• ЦПУ - 4 x AMD Ryzen 3 1200 Quad-Core

• ОЗУ - 8 Гб

• Диски - два SSD в ZFS

Из них 1-2 Гб ОЗУ забирает ОС гипервизора. Значит на контейнеры и виртуалки остаётся не так много ресурсов. Решил, что для 1-2 пользователей git-сервера хватит одного ядра, 512 Мб ОЗУ и 8 Гб диска.

Запуск контейнера с ОС Alpine

Настройка и запуск Alpine на Proxmox очень просты и удобны. Описывать их не буду. Скажу только, что мне эта тема с шаблонами очень понравилась. Жаль, что самих шаблонов не так много на мой взгляд.

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

alpine:~# apk search zabbix

Подготовка системы

Сменил имя хоста сервера:

alpine:~# hostname gogs-githost

Вначале я установил openssh и nano для его настройки, чтобы нормально подключаться по ssh:

gogs-githost:~# apk add openssh nano

Далее добавил демон в автозагрузку:

gogs-githost:~# rc-update add sshd

Поправил конфиг /etc/ssh/sshd_config и убрал комментарии строк:

...Port 22PermitRootLogin yes...

Всё, запустил демон:

gogs-githost:~# /etc/init.d/sshd start

Установка сервиса Gogs

Попытка первая

В документации к Alpine рекомендуют для разработки использовать Gitea. Но это слишком просто неть, поэтому выбрал другое. Я решил внаглую установить git-сервер командой:

gogs-githost:~# apk add gogsfetch http://dl-cdn.alpinelinux.org/alpine/v3.12/main/x86_64/APKINDEX.tar.gzfetch http://dl-cdn.alpinelinux.org/alpine/v3.12/community/x86_64/APKINDEX.tar.gz(1/8) Installing ca-certificates (20191127-r4)(2/8) Installing nghttp2-libs (1.41.0-r0)(3/8) Installing libcurl (7.69.1-r3)(4/8) Installing expat (2.2.9-r1)(5/8) Installing pcre2 (10.35-r0)(6/8) Installing git (2.26.3-r0)(7/8) Installing gogs (0.11.91-r1)Executing gogs-0.11.91-r1.pre-install(8/8) Installing gogs-openrc (0.11.91-r1)Executing busybox-1.31.1-r19.triggerExecuting ca-certificates-20191127-r4.triggerOK: 89 MiB in 38 packages

В результате, система помимо самого сервиса gogs установила ещё и дополнительные пакеты, например сам git. Пробую запустить сервер и получаю ошибку:

gogs-githost:~# gogs web2021/03/18 20:13:42 [ WARN] Custom config '/usr/bin/custom/conf/app.ini' not found, ignore this if you're running first time2021/03/18 20:13:42 [TRACE] Custom path: /usr/bin/custom2021/03/18 20:13:42 [TRACE] Log path: /usr/bin/log2021/03/18 20:13:42 [TRACE] Log Mode: Console (Trace)2021/03/18 20:13:42 [ INFO] Gogs 0.11.91.08112021/03/18 20:13:42 [ INFO] Cache Service Enabled2021/03/18 20:13:42 [ INFO] Session Service Enabled2021/03/18 20:13:42 [ INFO] SQLite3 Supported2021/03/18 20:13:42 [ INFO] Run Mode: Development2021/03/18 20:13:42 [FATAL] [...gogs/gogs/cmd/web.go:66 checkVersion()] Fail to read 'templates/.VERSION': open /usr/bin/templates/.VERSION: no such file or directory

Как мы видим, ему не хватает конфига и структуры каталогов для работы. Проверил каталог /usr/bin, там оказался лишь одинокий исполняемый файл gogs.

Попытка вторая

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

Тогда решил пойти другим путём - в документации Gogs описывается установка под популярные дистрибутивы Linux. Обнаружил там таблицу архивов под две версии Gogs, поэтому проверил, какой установился у меня на Alpine:

gogs-githost:~# gogs -vGogs version 0.11.91.0811

Решил попробовать вот этот. Скопировал его в директорию /opt на Alpine:

gogs-githost:/opt# wget https://dl.gogs.io/0.11.91/gogs_0.11.91_linux_amd64.tar.gz

Распаковал:

gogs-githost:/opt# tar -xvf gogs_0.11.91_linux_amd64.tar.gz

Мой замысел был в том, что либо он заработает после распаковки сразу, либо с него можно будет взять недостающей структуры и конфигов. Поменял права на директорию распакованного gogs:

gogs-githost:/opt# chown -R root:root gogs

Попробовал запустить и получил странную ошибку (спойлер: не удивительно, ведь С-компиляторы разные на Alpine это mysl, но об этом я узнаю позже):

gogs-githost:/opt/gogs# ./gogs web-ash: ./gogs: not found

Тогда то мне и пришла дикая идея подсунуть gogs из Alpine пакетов:

gogs-githost:/opt/gogs# cp /usr/bin/gogs gogs

И бинго! Сервер стартанул и я даже смог его настроить из веб-интерфейса. Но это был не конец

Попытка третья

Несмотря на охватившую меня эйфорию, радости и я у мамки сисадмин! весь следующий день я провёл в раздумьях. Мне не верилось, что в таком перспективном проекте как Alpine, есть место битому пакету. Чувство, что ошибка на моей стороне, не давала покоя.

Я нашел телеграм-чат по Alpine и (увы) на ломаном инглише объяснил свою проблему. Меня направили проверять конфиги в репозитории пакета gogs проекта Alpine.

Честно - у меня не получилось выяснить, в чём ошибка. Но добыл ценную инфу - сервер можно запускать с явным указанием пути к файлу конфига. Попробовал, и штатный gogs-сервер запустился:

gogs-githost:~# gogs web -c /etc/gogs/conf/app.ini2021/03/20 19:22:47 [TRACE] Custom path: /usr/bin/custom2021/03/20 19:22:47 [TRACE] Log path: /var/log/gogs2021/03/20 19:22:47 [TRACE] Log Mode: File (Info)2021/03/20 19:22:47 [ INFO] Gogs 0.11.91.0811

Дальше настраивал по этому видео-уроку, начиная с момента про настройку из веб-интерфейса.

Конечно, это не полная настройка. При настройке из GUI, я выяснил, что нужно ещё ставить bash.

Кроме этого, нужно настроить автозапуск сервера. Вернее, он уже есть - /etc/init.d/gogs, но не работает:

#!/sbin/openrc-runname=gogsconffile="$GOGS_CUSTOM/conf/app.ini"command="/usr/bin/gogs"command_args="web -c $conffile"start_stop_daemon_args="${GOGS_USER:+--user} $GOGS_USER --env GOGS_CUSTOM=$GOGS_CUSTOM"pidfile="/var/run/gogs.pid"command_background="yes"depend() {        use logger dns        need net        after firewall}

Путём перебора вариантов пришёл к такому:

#!/sbin/openrc-runname=gogsconffile="/etc/gogs/conf/app.ini"command="/usr/bin/gogs"command_args="web -c $conffile"start_stop_daemon_args="${GOGS_USER:+--user} root --env GOGS_CUSTOM=/etc/gogs"pidfile="/var/run/gogs.pid"command_background="yes"depend() {        use logger dns        need net        after firewall}

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

Как на самом деле нужно было

После такого долгого пути экспериментов и щупанья головой стены на прочность, меня осенило! Сервер не нужно запускать вручную, он должен стартовать вместе с системой. Значит, его надо настроить по аналогии с openssh.

Снова решил проверить - клонировал контейнер с Alpine и уже настроенным ssh. А дальше всё оказалось очень просто:

alpine:~# apk add gogsalpine:~# rc-update add gogs * service gogs added to runlevel defaultalpine:~# /etc/init.d/gogs start * Starting gogs ...                                                                     [ ok ]alpine:~# rc-statusRunlevel: default networking                                                                    [  started  ] sshd                                                                             [  started  ] crond                                                                            [  started  ] gogs                                                                             [  started  ]

Этого действительно достаточно, чтобы запустить свой Git-сервер (если вас устраивает БД SQLite). Теперь можно идти на веб-интерфейс, у меня это был http://192.168.50.205:3000, и делать базовые настройки.

Заключение

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

Но правда также и в том, что простой справки по развороту именно пакета gogs на Alpine я не нашёл. Надеюсь, моя статья будет полезна тем, кто задумает нечто подобное.

Над железомFlipper Zeroработают одновременно несколько инженеров. Коллективная работа над железным проектом это боль. У программистов есть крутые системы контроля версий и модные сервисы вроде GitHub, но бинарные файлы печатной платы и схем нельзя так просто засунуть в Git. Мы долго и мучительно искали решение этой проблемы и наконец нашли.

Altium 365 это система контроля версий с веб-интерфейсом для работы над железными проектами. Мы смогли перенести привычный воркфлоу GitHub на железную разработку. В посте я расскажу про наш опыт использования Altium 365 на примере реальной задачи в нашем проекте Flipper Zero.

Как разрабатывали железо раньше

Хардкорные ребята из отечественных НИИ привыкли вести версионность железных проектов в папках и архивах. На каждую версию просто создается папка. Такой подход очень легко ломается, когда внутри папки кто-то внезапно отредактировал и забыл изменить версию, и все потерялось.

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

Что если использовать GitHub?

Железо для Flipper Zero разрабатывается в Altium Designer силами трех инженеров. Вначале мы по привычке пробовали использовать GitHub для версионирования и коллективной работы, но это оказалось ОЧЕНЬ неудобно. Каждому инженеру приходилось долго согласовывать, кто в какой момент начнет работу над платой, ждать пока каждый закончит свои изменения и выгрузит их в Git, потому что в отличие от обычного кода, бинарные файлы нельзя так просто редактировать параллельно.

Минусы использования GitHub вместе с Alitum

• Нельзя сравнить бинарные файлы. Непонятно, чем один релиз отличается от другого. Каждый коммит обновляется сотни раз

• Нужно использовать отдельную программу для ведения репозитория

• Нельзя посмотреть содержимое проекта в веб-интерфейсе. Непонятно, что вообще находится в репозитории

• Неудобно готовить релизы. Итоговые Gerber-файлы нужно подкладывать руками в релиз

В итоге мы начали искать решение лучше.

Что такое Altium 365

Altium 365 это облачный сервис для коллективной работы над железом. В нем есть одновременно система контроля версий, предотвращения конфликтов, веб-интерфейс для просмотра и управления проектом. Десктопная версия Altium Designer подключается к удаленному серверу Altium 365, с которым синхронизирутся проекты, библиотеки компонентов и т.д. Изменения сохраняются на удаленный сервер, как обычные коммиты. Разработчики при этом работают в нативной десктопной программе Altium Designer как обычно.

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

Altium 365 глазами разработчика железа

Со стороны разрабочтика печатных плат работа с Altium365 выглядит так:

1. Разработчик авторизуется своим корпоративным аккаунтом в десктопном Altium Designer и подключается к удаленному воркспейсу. Вся работа происходит в нативной десктопной программе, не в браузере.

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

3. После внесения изменений в проект выполняется коммит с комментарием и пуш на сервер, точно так же, как это делается в Git.

Предотвращение конфликтов

Для предотвращения конфликтов, когда два разработчика одновременно вносят изменения в один файл, в списке файлов появляется иконка о том, что файл уже редактируется другим пользователем. Можно видеть его имя и согласовать работу.

Сохранение на сервер

После завершения работы изменения можно сохранить на сервере. Для простоты есть кнопкаSave to Server, которая по сути выполняет локальный коммит и пуш. В коммите можно ввести комментарий, описывающий изменения.

Общая библиотека компонентов

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

Веб-интерфейс Altium 365

Сервер Altium 365 имеет веб-интерфейс. В нашей компании к нему имеют доступ все инженеры: тестировщики, программисты, механики (разработчики корпуса). Это ОЧЕНЬ удобный инструмент, позволяющий из браузера и без установки программ быстро иметь доступ ко всей схемотехнике и 3D-моделям плат.

Зачем нужен веб-интерфейс Altium 365

• Просматривать файлы проекта: схемы, герберы, 3D-модели, искать нужны компоненты на плате, дорожки т.д. ИЗ БРАУЗЕРА(!!!)

• История коммитов. Можно отслеживать, когда и кто вносил изменения в проект. Это удобно для менеджеров, отслеживающих выполнение задач и всех членов команды. Любой коммит можно скачать отдельно или клонировать в отдельный репозиторий.

• Система комментариев. Тестировщик может выделить нужную область или компонент на плате и написать комментарий для разработчика.

• Оформление релизов для производства.

История коммитов и релизов

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

Также в истории публикуются релизы проекта. Это готовые наборы герберов и прочих файлов для производства, которые отправляются на завод. Их можно расшарить прямо в веб-интерфейсе, указав email получателя.

Просмотр схемы

Во вкладке SCH находится интерактивный просмотрщик схемы. Он умеет показывать информацию о компонентах и цепях. Можно выделить нужный компонент или дорожку на схеме и перейти к ней на 3D-модели или плате. Удобно при отладке физической платы.

Просмотр платы

Во вкладке PCB интерактивный вьювер платы. Так же, как и во вьювере схемы, можно выделить каждый компонент и посмотреть информацию о нем, и как он выглядит на схеме и в 3D. Слева можно включить отображение платы по слоям.

3D-модель

Вьювер 3D-модели тоже интерактивный. Любой компонент можно выделить и найти его на схеме или во вьювере PCB. При этом все работает нативно в браузере на WebGL, без установки плагинов и программ.

Комментарии

Во вьюверах PCB и SCH можно оставить комментарий под компонентом или областью. Комментарий будет виден всем в веб-интерфейсе и разработчикам в десктопной программе. У каждого комментария можно поставить статус Resolved, то есть использовать их как задачи для правок.

Благодарности команде Altium

Мы пользуемся Altium 365 каждый день и очень рады, что больше не нужно страдать. От лица нашей компании Flipepr Devices хочу выразить благодарность команде Altium за удобный инструмент, который мы используем каждый день, и отдельное спасибо за поддержку, помощь в настройке и обучении.

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

Как попробовать Altium 365

Для маленьких команд и стартапов есть программаAltium Launchpad, по которой можно приобрести лицензию на Altium со скидкой.

Также рекомендую русскоязычный чат в Telegram@Altium_and_electronics,где можно пообщаться с пользователями и разработчиками самого Altium.

На собеседованиях на позицию, предполагающую понимание DevOps, я люблю задавать кандидатам такой вопрос (а иногда его еще задают и мне):

Каким, по вашему мнению, должен быть идеальный пайплайн от коммита до продашкена?/Опишите идеальный CI/CD / etc

Сегодня я хочу рассказать про своё видение идеального пайплайна. Материал ориентирован на людей, имеющих опыт в построении CI/CD или стремящихся его получить.

Почему это важно?

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

2. Кандидат начинает рассуждать, а в крутых специалистах ценится именно умение думать.

3. Когда в вопрос добавляется такое абсолютное прилагательное, как "идеальный", то мы сразу развязываем кандидатам руки в просторе для творчества и фантазий. У соискателей появляется возможность показать, какие улучшения они видят (или не видят) в текущей работе, и что хотели бы добавить сами. Также мы можем узнать, есть ли у нашего предполагаемого будущего коллеги мотивация к улучшениям процессов, ведь концепция "работает не трогай" не про динамичный мир DevOps.

4. Организационная проверка. Позволяет узнать, насколько широка картина мира у соискателя. Условно: от создания задачи в Jira до настроек ноды в production. Сюда же можно добавить понимание стратегий gitflow, gitlabFlow, githubFlow.

Итак, прежде чем перейти к построению какого-либо процесса CI, необходимо определиться, а какие шаги нам доступны?

Что можно делать в CI?

• сканить код;

• билдить код;

• тестить код;

• деплоить приложение;

• тестить приложение;

• делать Merge;

• просить других людей подтверждать MR через code review.

Рассмотрим подробнее каждый пункт.

Code scanning

На этой стадии основная мысль никому нельзя верить.

Даже если Вася Senior/Lead Backend Developer. Несмотря на то, что Вася хороший человек/друг/товарищ и кум. Человеческий фактор, это все еще человеческий фактор.

Необходимо просканировать код на:

• соотвествие общему гайдлайну;

• уязвимости;

• качество.

Задачи на этой стадии следует выполнять параллельно.

И триггерить только если меняются исходные файлы, или только если было событие git push.

Пример для gitlab-ci

stages:  - code-scanning.code-scanning: only: [pushes] stage: code-scanning 

Linters

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

Самая важная задача линтеров приводить код к единообразию.

После внедрения этой штучки разработчики начнут вас любить. Потому что они наконец-то начнут понимать друг друга. Или ненавидеть, решив, что вы вставляете им палки в колеса линтеры в CI. Это уже зависит от ваших soft skills, культуры и обмена знаниями.

Инструменты

Code Quality

code quality этими инструментами могут быть как продвинутые линтеры, так и совмещающие в себе всякие ML-модели на поиск слабых мест в коде: утечек памяти, небезопасных методов, уязвимостей зависимостей и т.д, перетягивая на себя еще code security компетенции.

Инструменты

Code Security

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

1. Бороться с утечкой паролей/ключей/сертификатов.

2. Cканировать на известные уязвимости.

Неважно, насколько большая компания, люди в ней работают одинаковые. Если разработчик "ходит" в production через сертификат, то для своего удобства разработчик добавит его в git. Поэтому придется потратить время, чтобы объяснить, что сертификат должен храниться в vault, а не в git

Инструменты

Сканер уязвимостей необходимо запускать регулярно, так как новые уязвимости имеют свойство со временем ВНЕЗАПНО обнаруживаться.

Code Coverage

Ну и конечно, после тестирования, нужно узнать code coverage.

Процент исходного кода программы, который был выполнен в процессе тестирования.

Инструменты

Unit test

Модульные тесты имеют тенденцию перетекать в инструменты code quality, которые умеют в юнит тесты.

Инструменты

Build

Этап для сборки artifacts/packages/images и т.д. Здесь уже можно задуматься о том, каким будет стратегия версионирования всего приложения.

За модель версионирования вы можете выбрать:

• semVer (пример с gitflow);

• romVer;

• номер cборки;

• datetime, timestamp;

• etc

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

Инструменты для сборки образов

Итак, сборка прошла успешно идем дальше.

Scan package

Пакет/образ собрали. Теперь нужно просканировать его на уязвимости. Современные registry уже содержат инструментарий для этого.

Инструменты

Deploy

Стадия для развертывания приложения в различных окружениях.

Не все окружения хорошо сочетаются со стратегиями развертывания.

• rolling классика;

• recreate все что угодно, но не production;

• blue/green в 90% процентов случаев этот способ применим только к production окружениям;

• canary в 99% процентов случаев этот способ применим только к production окружениям.

Stateful

Нужно еще помнить, что даже имея одинаковый код в stage и production, production может развалиться именно из-за того, что stateful у них разный. Миграции могут отлично пройти на пустой базе, но появившись на проде, сломать зеленые кружочки/галочки в пайплайне. Поэтому для stage/pre-production следует предоставлять обезличенный бэкап основной базы.

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

Инструменты

На правах рекламы скажу что helmwav'у очень не хватает ваших звезд на GitHub. Первая публикация про helmwave.

Integration testing

Приложение задеплоили. Оно где-то живет в отдельном контуре.Наступает этап интеграционного тестирования. Тестирование может быть как ручным, так и автоматизированным. Автоматизированные тесты можно встроить в пайплайн.

Инструменты

Performance testing (load/stress testing)

Данный вид тестирования имеет смысл проводить на stage/pre-production окружениях. С тем условием, что ресурсные мощности на нем такие же, как в production.

Инструменты, чтобы дать нагрузку

Инструменты, чтобы оценить работу сервиса

Code Review / Approved

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

Список команд/ролей:

• QA;

• Security;

• Tech leads;

• Release managers;

• Maintainers;

• DevOps;

• etc.

Очевидно, что созывать весь консилиум перед каждым MR не нужно, каждая команда должна появится в свой определённый момент MR:

• вызывать безопасников имеет смысл только перед сливанием в production;

• QA перед release ветками;

• DevOps'ов беспокоить, только если затрагиваются их компетенции: изменения в helm-charts / pipeline / конфигурации сервера / etc.

Developing flow

Чаще всего каждая компания, а то и каждый проект в компании, решает изобрести свой велосипед-флоу. Что после нескольких итераций приходит к чему-то, что может напоминать gitflow, gitlabFlow, githubFlow или все сразу.

Это и не хорошо, и не плохо это специфика проекта. Есть мнения, что gitflow не торт. GithubFlow для относительно маленьких команд. А про gitlabFlow мне нечего добавить, но есть наблюдение, что его не очень любят продакты - за то, что нельзя отслеживать feature-ветки.

Если вкратце, то:

• Gitflow: feature -> develop -> release-vX.X.X -> master (aka main) -> tag;

• GitHubFlow: branch -> master (aka main);

• GitLabFlow: environmental branches.

TL;DR

Общий концепт

_

Feature-ветка

Pre-Production -> Production

P.S.

Если я где-то опечатался, упустил важную деталь или, по вашему мнению, пайплайн недостаточно идеальный, напишите об этом мне сделаю update.

Разработчик создал ветку и запушил в нее код. Что дальше?

Оставляйте варианты ваших сценариев в комментариях.