Написание хороших PR и README

Почему техническое письмо важно

В Code Review описание PR — это входная точка для ревьюера. Хорошее описание PR:

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

Совет

Техническое письмо — не творческая литература. Здесь есть формулы и шаблоны, и, освоив их, можно писать очень хорошо.

Стандартная структура PR: What/Why/How/Testing

1. What (что сделано)

Краткое резюме, одно предложение.

Refactor authentication flow to support OAuth2 and magic link sign-up

Ключевые выражения:

• Add X — добавление новой функции
• Fix X — исправление бага
• Refactor X — переписывание кода (без изменения функциональности)
• Optimize X — улучшение производительности
• Implement X — реализация определённого дизайна

2. Why (почему)

Наиболее часто пропускаемая часть. Объясните контекст и мотивацию.

Why:
- Users requested passwordless sign-up option
- Current session-based auth doesn't scale to multiple domains
- OAuth2 is industry standard for enterprise integrations

Осторожно

“Because I wanted to” — не хорошее обоснование. Укажите реальную причину.

3. How (как)

Высокоуровневый обзор технической реализации.

How:
1. Created JWT service using Web Crypto API for signing/verification
2. Replaced SessionMiddleware with AuthMiddleware that validates JWT
3. Added OAuth2 routes for Google/GitHub sign-in
4. Migrated user session storage from cookie to JWT claims

Breaking changes:
- Moved user auth state from server session to JWT (stateless)
- Clients now need to store and send JWT in Authorization header

4. Testing (как тестировали)

Testing:
- Manual testing: Verified OAuth2 sign-in with Google and GitHub accounts
- Existing auth tests pass (147 tests)
- Added 23 new tests for JWT and OAuth2 flows
- Load tested with 1000 concurrent requests (no issues)

Заметка

Раздел “Testing” важен — он сообщает ревьюерам, что вы уже протестировали, и им не нужно искать баги.

Грамматические ловушки технического письма

1. Времена (самая частая ошибка)

Принцип: настоящее время для описания работы кода, прошедшее — для описания ваших изменений

Ошибка	Причина	Правильно
”The function was created to handle X”	Звучит как исторический рассказ	”The function handles X"
"The code will validate input”	Слишком неопределённо	”The code validates input”

2. Артикли (типичная ошибка русскоязычных)

Принцип: при первом упоминании “a/an”, далее “the”; или используйте множественное число, чтобы избежать артиклей

Ошибка	Правильно
”We refactored authentication flow"	"We refactored the authentication flow"
"Function handles case when user logs in"	"The function handles the case when a user logs in”

3. Избыточный пассивный залог

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

Пассивный	Активный (лучше)
“The JWT is generated by the server"	"The server generates the JWT"
"Breaking changes were introduced"	"This PR introduces breaking changes”

4. Тонкие различия синонимов

Слово	Использование
Add	Добавление совершенно новой функции: “Add OAuth2 support”
Implement	Реализация известного дизайна: “Implement the design from #123”
Refactor	Улучшение существующего кода без изменения функциональности: “Refactor auth middleware”
Optimize	Повышение производительности: “Optimize query performance”
Fix	Исправление бага: “Fix race condition in cache”

Чек-лист PR-описания

Перед отправкой PR проверьте:

• What — ясно описывает изменение
• Why — есть бизнес- или техническое обоснование
• How — высокоуровневый дизайн понятен ревьюеру
• Testing — описано покрытие тестами
• Нет избыточного пассивного залога
• Артикли использованы правильно (“the” vs “a”)
• Времена согласованы
• Есть ссылки на связанные issue (при наличии)