Коммитс (англ. commitics) — документальный разбор настоящей ошибки в открытом проекте, собранный из коммитов, PR и переписки.
Каждый заход даёт два результата: публичный разбор с цитатами и ссылками — и внутренний вывод про свой код. Второй обязателен: разбор без него — чтение, а не работа.
Жанр развлекательный, а не учебный. Читатель пришёл за историей, а не за уроком. Польза извлекается сама, потому что история настоящая.
- Кадр — это коммит, PR или реплика. У каждого есть дата, автор и одно событие. «29 июня 2022 приезжает коммит
Add a few strategies» — кадр. «Разработчики добавили стратегии» — пересказ. - Даты вслух. Не «позже», а «через год и четыре месяца». Промежуток — половина драматургии.
- Название коммита — реплика персонажа. Их не пересказывают, их приводят.
- Одно событие — один абзац.
- Последствие показывается, а не называется. Не «некорректный расчёт», а «кнопка ‘убрать скидку’ выдавала максимальную».
- Пуант в конце. Заголовок интригует, но не раскрывает.
- Тестов и опросов в конце нет. Вопрос с четырьмя вариантами превращает историю в проверочную работу. Вывод — да, экзамен — нет.
Главное — люди, а не код. Читателю интересно место, где работают программисты: команда, ревью, спор, решение, которое кому-то пришлось защищать. Код — повод, а не содержание.
Что искать в первую очередь:
- ревью с возражением — кто-то сказал «так нельзя» и оказался прав (или не оказался, и это ещё интереснее);
- PR, который защищали — автор отвечает на замечания, меняет подход, спорит с мейнтейнером;
- откат, который пришлось объяснять — решение прожило и было отменено;
- мейнтейнер против контрибьютора, команда против сроков, двое несогласных и третий, который принял решение;
- честно названная цена: «мы знаем, что это плохо, и вот почему оставили».
Проект с командой ценнее одиночного репозитория. Не из снобизма: где есть процесс, там есть переписка, а где есть переписка — есть ход мысли. В репо одного человека решение принимается молча, и восстанавливать нечего.
Сгенерированное допустимо, но это не цель. У генерации не бывает ни спора, ни второй стороны, ни человека, который за неё отвечает.
Свой код — короткий хвост, а не половина текста. Проверка обязательна — она делает работу работой, а не чтением. Но читателю она неинтересна: абзац-два, конкретно. Всё остальное место принадлежит чужой истории и людям в ней.
Отдельная линия внутри разборов — портреты. Код меняется и забывается, люди остаются; и читателю, который сам не программист, интересны именно они. Наблюдаем за поведением в среде обитания — а среда обитания у них репозиторий.
Черта называется только вместе с поступком. Не «упорный», а «вернулся через два месяца после того, как задачу закрыли по неактивности, и довёл её ещё за год». Не «принципиальный», а «повторил одно и то же возражение трижды за месяц, ни разу не смягчив». Поступок — с датой и ссылкой. Нет поступка — нет черты.
Это наблюдение, а не диагноз. Описываем, что человек сделал и написал, а не какой он. «Похоже, выгорел», «видимо, интроверт» — запрещено так же, как домысливание мотивов. Сам написал, что устал, — цитируем.
Что стоит замечать:
- преданность — сколько месяцев человек не бросал и что делал в паузах;
- принципиальность — возражение, которое не размякло под давлением сроков;
- честность против своих — редчайшее: человек из проекта X говорит, что для X так делать не надо. Такое стоит целого разбора;
- щедрость — мейнтейнер, который вместо «закрыто» пишет, что именно сделать;
- аккуратность — пометил догадку словом «предположительно», записал замер, оставил отвергнутый вариант с надписью «пробовали, плохо»;
- умение признать — «я был неправ», сказанное публично и без оговорок.
Тон — как в фильме про природу: с интересом и уважением. Смешное — в положении, никогда в человеке. Разница простая: «шестнадцать месяцев ради одной команды в консоли» — наблюдение; «сидел и упирался» — насмешка. Первое читается с симпатией, второе только с чувством превосходства, а его в разборах быть не должно: мы попадаем в них наравне.
Проект тоже персонаж. У него есть повадки: как принимает чужаков, что делает с плохими предложениями, пишет ли в коде, почему решил так. Проект, где мейнтейнер объясняет отказ на пятнадцать строк, и проект, где закрывают молча, — разные виды, и это видно с первого захода.
Имя ставится там, где человек что-то сделал или сказал. Автор цитаты, автор коммита, автор починки. Это и точность, и уважение.
«Кто сломал» — обычно неизвестно и почти всегда неважно. git blame показывает последнего, кто трогал строку. Герой разбора — тот, кто нашёл; злодей — обстоятельства.
Мотивы не домысливаются. «Разработчик, вероятно, торопился» — это выдумка про живого человека под его именем. Не написано — значит неизвестно.
Юмор про положение, а не про людей. Смешное почти всегда в самой ситуации. Насмешка над автором и нечестна, и скучна.
Мы попадаем в разборы наравне. Если та же ошибка нашлась у нас — так и пишется, с тем же тоном. Это единственное, что делает остальное честным.
На урезанном клоне поиск по содержимому коммитов не работает — а именно он находит, когда строка появилась и что было до неё.
git clone https://github.com/OWNER/REPO && cd REPO && git log -S "ключевое слово" --onelineВ названиях коммитов ищите «back to», «revert», «actually», «fix race», «properly». Самые ценные места — те, где решение приняли, пожили с ним и отменили.
git log --oneline -- путь/к/файлуОписания PR и комментарии в задачах часто ценнее кода: там объясняют, почему НЕ сделали правильнее. Там же слова пострадавшего.
gh api repos/OWNER/REPO/issues/N/comments --jq '.[]|"\(.user.login) \(.created_at[0:10])\n\(.body)"'Кадр — это событие: строки появились, изменились или исчезли. Событие показывает commit/<sha> — там сразу дифф, автор, дата и сообщение. Если код цитируется дословно — добавьте построчную ссылку на тот же SHA: blob/<sha>/путь#L28-L52.
gh api repos/OWNER/REPO/commits/main --jq .shaЦена почти всегда описана не в коде, а в разделе для пользователей про ошибки и ограничения — там она честнее.
Греп, тест или правка. Если у вас всё хорошо — так и напишите, назвав конкретные места и почему они устойчивы.
Полчаса поисков без цепочки «сделали так → столкнулись с тем-то → починили этак → объяснили словами» — тема закрывается, берẻтся другая.
Переносится в любой проект как есть — подставьте тему.
Найди и разбери настоящую историю ошибки в открытом проекте по теме «ТЕМА» (например: очередь задач, списание бонусов, ограничение частоты, часовые пояса, загрузка файлов).
Где искать. Полный
git clone(не--filter=blob:none— на нёмgit log -Sумирает). Дальше:
git log -S "ключевое слово"— когда строка появилась и что было до;git log --oneline -- путь/к/файлу— искать откаты и переписывания: «back to», «revert», «actually», «fix race», «properly»;gh api repos/ВЛАДЕЛЕЦ/РЕПО/pulls/Nи…/issues/N/comments— описания и переписка. Часто ценнее кода: там объясняют, почему не сделали правильнее;- задача, на которую ссылается PR: там слова пострадавшего;
- документация проекта: там цена решения, описанная для пользователя.
Что считается хорошей находкой. Не «нашёл баг», а нашлась цепочка: кто-то сделал так → столкнулись с тем-то → починили этак → и объяснили словами почему.
И главное — в цепочке должны быть ЛЮДИ. Интересно место, где работают программисты: команда, ревью, спор, решение, которое кому-то пришлось защищать или отменять. Ищи в первую очередь возражение в ревью, PR, который автор отстаивал, откат, который объясняли, несогласие мейнтейнера с контрибьютором, честно названную цену («знаем, что плохо, оставили вот почему»). Проект с командой ценнее одиночного репозитория: где есть процесс, там есть переписка, а где переписка — там ход мысли. Сгенерированный код допустим как материал, но у генерации нет ни спора, ни второй стороны, ни человека, который за неё отвечает.
Что написать. Публичный разбор — и коротким хвостом внутренний вывод. Вывод обязан заканчиваться проверкой своего кода — грепом, тестом, правкой; если всё хорошо, так и напиши, назвав конкретные места и почему они устойчивы. Но это абзац-два, а не половина текста.
Ссылка на код — в каждом пункте, где код упоминается. По умолчанию — на КОММИТ. Кадр это событие: строки появились, изменились или исчезли, а показывает это
https://github.com/ВЛАДЕЛЕЦ/РЕПО/commit/<sha>— сразу с диффом, автором и датой. Если код цитируется дословно, рядом ставится построчная ссылка на тот же SHA:blob/<полный-sha>/путь/файл.ts#L574-L590. Обе заморожены SHA и не протухают; протухает только ссылка на ветку (blob/main/…): там строки уедут, и читатель откроет чужой код на том же номере. SHA:git rev-parse HEADв клоне илиgh api repos/О/Р/commits/main --jq .sha; на сайте GitHub — клавишаy. В шаге списка ссылка кладётся вrefs, а не в текст.Правила точности. Цитаты дословные и со ссылкой, перевод рядом с оригиналом. Имена — там, где человек что-то сказал или сделал. Мотивы не домысливать: не написано — значит неизвестно. «Кто сломал» по
git blameне устанавливается — он показывает, кто трогал строку последним.Остановка. Полчаса поисков без цепочки — тема закрывается, берётся другая. Разборы делаются рядом с разработкой, а не вместо неё.