From:To:
11¶ **Коммитс** (англ. *commitics*) — документальный разбор настоящей ошибки в открытом проекте, собранный из коммитов, PR и переписки.
22
33 Каждый заход даёт **два результата**: публичный разбор с цитатами и ссылками — и внутренний вывод про свой код. Второй обязателен: разбор без него — чтение, а не работа.
44¶ ### Форма: комикс, а не отчёт
55
66 **Жанр развлекательный, а не учебный.** Читатель пришёл за историей, а не за уроком. Польза извлекается сама, потому что история настоящая.
77
88 - **Кадр — это коммит, PR или реплика.** У каждого есть дата, автор и одно событие. «29 июня 2022 приезжает коммит `Add a few strategies`» — кадр. «Разработчики добавили стратегии» — пересказ.
99 - **Даты вслух.** Не «позже», а «через год и четыре месяца». Промежуток — половина драматургии.
1010 - **Название коммита — реплика персонажа.** Их не пересказывают, их приводят.
1111 - **Одно событие — один абзац.**
1212 - **Последствие показывается, а не называется.** Не «некорректный расчёт», а «кнопка ‘убрать скидку’ выдавала максимальную».
1313 - **Пуант в конце.** Заголовок интригует, но не раскрывает.
1414 - **Тестов и опросов в конце нет.** Вопрос с четырьмя вариантами превращает историю в проверочную работу. Вывод — да, экзамен — нет.
1515¶ ### Что считается хорошей находкой
1616
1717 **Главное — люди, а не код.** Читателю интересно место, где работают программисты: команда, ревью, спор, решение, которое кому-то пришлось защищать. Код — повод, а не содержание.
1818
1919 Что искать в первую очередь:
2020
2121 - **ревью с возражением** — кто-то сказал «так нельзя» и оказался прав (или не оказался, и это ещё интереснее);
2222 - **PR, который защищали** — автор отвечает на замечания, меняет подход, спорит с мейнтейнером;
2323 - **откат, который пришлось объяснять** — решение прожило и было отменено;
2424 - **мейнтейнер против контрибьютора**, команда против сроков, двое несогласных и третий, который принял решение;
2525 - **честно названная цена**: «мы знаем, что это плохо, и вот почему оставили».
2626
2727 **Проект с командой ценнее одиночного репозитория.** Не из снобизма: где есть процесс, там есть переписка, а где есть переписка — есть ход мысли. В репо одного человека решение принимается молча, и восстанавливать нечего.
2828
2929 **Сгенерированное допустимо, но это не цель.** У генерации не бывает ни спора, ни второй стороны, ни человека, который за неё отвечает.
3030
3131 **Свой код — короткий хвост, а не половина текста.** Проверка обязательна — она делает работу работой, а не чтением. Но читателю она неинтересна: абзац-два, конкретно. Всё остальное место принадлежит чужой истории и людям в ней.
32+¶ ### Рубрика: в мире программистов
33+
34+ Отдельная линия внутри разборов — **портреты**. Код меняется и забывается, люди остаются; и читателю, который сам не программист, интересны именно они. Наблюдаем за поведением в среде обитания — а среда обитания у них репозиторий.
35+
36+ **Черта называется только вместе с поступком.** Не «упорный», а «вернулся через два месяца после того, как задачу закрыли по неактивности, и довёл её ещё за год». Не «принципиальный», а «повторил одно и то же возражение трижды за месяц, ни разу не смягчив». Поступок — с датой и ссылкой. Нет поступка — нет черты.
37+
38+ **Это наблюдение, а не диагноз.** Описываем, что человек сделал и написал, а не какой он. «Похоже, выгорел», «видимо, интроверт» — запрещено так же, как домысливание мотивов. Сам написал, что устал, — цитируем.
39+
40+ **Что стоит замечать:**
41+
42+ - **преданность** — сколько месяцев человек не бросал и что делал в паузах;
43+ - **принципиальность** — возражение, которое не размякло под давлением сроков;
44+ - **честность против своих** — редчайшее: человек из проекта X говорит, что для X так делать не надо. Такое стоит целого разбора;
45+ - **щедрость** — мейнтейнер, который вместо «закрыто» пишет, что именно сделать;
46+ - **аккуратность** — пометил догадку словом «предположительно», записал замер, оставил отвергнутый вариант с надписью «пробовали, плохо»;
47+ - **умение признать** — «я был неправ», сказанное публично и без оговорок.
48+
49+ **Тон — как в фильме про природу: с интересом и уважением.** Смешное — в положении, никогда в человеке. Разница простая: «шестнадцать месяцев ради одной команды в консоли» — наблюдение; «сидел и упирался» — насмешка. Первое читается с симпатией, второе только с чувством превосходства, а его в разборах быть не должно: мы попадаем в них наравне.
50+
51+ **Проект тоже персонаж.** У него есть повадки: как принимает чужаков, что делает с плохими предложениями, пишет ли в коде, почему решил так. Проект, где мейнтейнер объясняет отказ на пятнадцать строк, и проект, где закрывают молча, — разные виды, и это видно с первого захода.
3252¶ ### Правила, из-за которых это работает
3353
3454 **Имя ставится там, где человек что-то сделал или сказал.** Автор цитаты, автор коммита, автор починки. Это и точность, и уважение.
3555
3656 **«Кто сломал» — обычно неизвестно и почти всегда неважно.** `git blame` показывает последнего, кто трогал строку. Герой разбора — тот, кто нашёл; злодей — обстоятельства.
3757
3858 **Мотивы не домысливаются.** «Разработчик, вероятно, торопился» — это выдумка про живого человека под его именем. Не написано — значит неизвестно.
3959
4060 **Юмор про положение, а не про людей.** Смешное почти всегда в самой ситуации. Насмешка над автором и нечестна, и скучна.
4161
4262 **Мы попадаем в разборы наравне.** Если та же ошибка нашлась у нас — так и пишется, с тем же тоном. Это единственное, что делает остальное честным.
4363## Как искать
44641. Клонировать целиком, без урезания истории
4565 На урезанном клоне поиск по содержимому коммитов не работает — а именно он находит, когда строка появилась и что было до неё.
4666 $ git clone https://github.com/OWNER/REPO && cd REPO && git log -S "ключевое слово" --oneline
4767 why: Без истории остаётся только текущее состояние кода, а разбор делается из изменений, а не из состояния.
4868 - [ ] Репозиторий клонирован с полной историей
49692. Искать откаты и переписывания, а не баги
5070 В названиях коммитов ищите «back to», «revert», «actually», «fix race», «properly». Самые ценные места — те, где решение приняли, пожили с ним и отменили.
5171 $ git log --oneline -- путь/к/файлу
5272 why: Откат — это готовая драматургия с двумя точками во времени и измеренной ценой решения.
5373 - [ ] Найдена цепочка из двух и более событий, а не одиночный фикс
54743. Читать переписку, а не только дифф
5575 Описания PR и комментарии в задачах часто ценнее кода: там объясняют, почему НЕ сделали правильнее. Там же слова пострадавшего.
5676 $ gh api repos/OWNER/REPO/issues/N/comments --jq '.[]|"\(.user.login) \(.created_at[0:10])\n\(.body)"'
5777 why: Ход мысли восстанавливается только по написанному. Всẻ остальное — беллетристика с чужими именами.
5878 - [ ] Есть хотя бы одна дословная цитата со ссылкой
5979 - [ ] К каждой цитате есть перевод рядом, а не вместо
6080 → GitHub: постоянные ссылки на код — https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files
61814. Закрепить ссылку на код — по умолчанию на коммит
6282 Кадр — это событие: строки появились, изменились или исчезли. Событие показывает `commit/<sha>` — там сразу дифф, автор, дата и сообщение. Если код цитируется дословно — добавьте построчную ссылку на тот же SHA: `blob/<sha>/путь#L28-L52`.
6383 $ gh api repos/OWNER/REPO/commits/main --jq .sha
6484 why: Обе ссылки заморожены SHA и не протухают; разница в том, что коммит показывает ИЗМЕНЕНИЕ, а blob — СОСТОЯНИЕ. Жанр про изменения. Протухает только ссылка на ветку: `blob/main/…` через месяц покажет чужой код на том же номере.
6585 - [ ] Ни одной ссылки вида blob/main или tree/main — везде SHA
6686 - [ ] У каждого кадра-события есть ссылка на коммит или PR
6787 - [ ] У каждой дословной цитаты кода есть построчная ссылка
6888 - [ ] Ссылка открыта и проверено, что там именно тот код
6989 → GitHub: постоянные ссылки на строки кода — https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files
70905. Посмотреть документацию проекта: там цена решения [recommended]
7191 Цена почти всегда описана не в коде, а в разделе для пользователей про ошибки и ограничения — там она честнее.
7292 why: «Выдернули шнур — задача ждёт четыре часа» встречается в документации, а не в исходниках.
7393 - [ ] Цена решения найдена и процитирована словами самого проекта
7494## Чем заканчивать
75956. Проверить СВОЙ код по той же болезни
7696 Греп, тест или правка. Если у вас всё хорошо — так и напишите, назвав конкретные места и почему они устойчивы.
7797 why: Разбор без проверки своего кода — чтение, а не работа. Именно этот шаг окупает время.
7898 - [ ] Названы конкретные файлы и строки, а не «у нас такого нет»
7999 - [ ] Если нашлось — есть коммит или задача, а не намерение
801007. Остановиться, если цепочки нет
81101 Полчаса поисков без цепочки «сделали так → столкнулись с тем-то → починили этак → объяснили словами» — тема закрывается, берẻтся другая.
82102 why: Разборы делаются рядом с разработкой, а не вместо неё. Высиженная тема всегда видна по натянутости.
83103 - [ ] Заход уложился в час вместе с проверкой своего кода
84104¶ ### Готовый промпт
85105
86106 Переносится в любой проект как есть — подставьте тему.
87107
88108 > Найди и разбери настоящую историю ошибки в открытом проекте по теме **«ТЕМА»** (например: очередь задач, списание бонусов, ограничение частоты, часовые пояса, загрузка файлов).
89109 >
90110 > **Где искать.** Полный `git clone` (не `--filter=blob:none` — на нём `git log -S` умирает). Дальше:
91111 > - `git log -S "ключевое слово"` — когда строка появилась и что было до;
92112 > - `git log --oneline -- путь/к/файлу` — искать **откаты и переписывания**: «back to», «revert», «actually», «fix race», «properly»;
93113 > - `gh api repos/ВЛАДЕЛЕЦ/РЕПО/pulls/N` и `…/issues/N/comments` — описания и переписка. Часто ценнее кода: там объясняют, **почему не сделали правильнее**;
94114 > - задача, на которую ссылается PR: там слова пострадавшего;
95115 > - документация проекта: там цена решения, описанная для пользователя.
96116 >
97117 > **Что считается хорошей находкой.** Не «нашёл баг», а нашлась цепочка: кто-то сделал так → столкнулись с тем-то → починили этак → и объяснили словами почему.
98118 >
99119 > **И главное — в цепочке должны быть ЛЮДИ.** Интересно место, где работают программисты: команда, ревью, спор, решение, которое кому-то пришлось защищать или отменять. Ищи в первую очередь возражение в ревью, PR, который автор отстаивал, откат, который объясняли, несогласие мейнтейнера с контрибьютором, честно названную цену («знаем, что плохо, оставили вот почему»). Проект с командой ценнее одиночного репозитория: где есть процесс, там есть переписка, а где переписка — там ход мысли. Сгенерированный код допустим как материал, но у генерации нет ни спора, ни второй стороны, ни человека, который за неё отвечает.
100120 >
101121 > **Что написать.** Публичный разбор — и коротким хвостом внутренний вывод. Вывод обязан заканчиваться **проверкой своего кода** — грепом, тестом, правкой; если всё хорошо, так и напиши, назвав конкретные места и почему они устойчивы. Но это абзац-два, а не половина текста.
102122 >
103123 > **Ссылка на код — в каждом пункте, где код упоминается. По умолчанию — на КОММИТ.** Кадр это событие: строки появились, изменились или исчезли, а показывает это `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`, а не в текст.
104124 >
105125 > **Правила точности.** Цитаты дословные и со ссылкой, перевод рядом с оригиналом. Имена — там, где человек что-то сказал или сделал. Мотивы не домысливать: не написано — значит неизвестно. «Кто сломал» по `git blame` не устанавливается — он показывает, кто трогал строку последним.
106126 >
107127 > **Остановка.** Полчаса поисков без цепочки — тема закрывается, берётся другая. Разборы делаются рядом с разработкой, а не вместо неё.