diff --git a/repo-checklist/repo-checklist-full.md b/repo-checklist/repo-checklist-full.md new file mode 100644 index 0000000..7b845f0 --- /dev/null +++ b/repo-checklist/repo-checklist-full.md @@ -0,0 +1,165 @@ + + +# Чеклист по оформлению репозитория + +## Основной чеклист + +| № | Пункт | Выполнено | +| --- | ------- | ----------- | +| 1 | Лицензия | ☐ | +| 2 | Лицензия правильно применяется к репозиторию | ☐ | +| 3 | Используемые третьесторонние компоненты и материалы совместимы с лицензией | ☐ | +| 4 | Настроенный CI | ☐ | +| 5 | Тесты в CI | ☐ | +| 6 | Линтер в CI | ☐ | +| 7 | В репозитории нет результатов сборки, настроен `.gitignore` | ☐ | +| 8 | В репозитории нет секретной информации (паролей, ключей и т.п.) | ☐ | +| 9 | Различные сторонние анализаторы (если уместно) | ☐ | +| 10 | Для кода на С/С++: использование санитайзеров | ☐ | +| 11 | `README.md`, плашки CI и анализаторов | ☐ | +| 12 | `README.md`, общее описание проекта | ☐ | +| 13 | `README.md`, пример использования | ☐ | +| 14 | `README.md`, инструкция по сборке и запуску | ☐ | +| 15 | `README.md`, как помочь проекту (если уместно) | ☐ | +| 16 | `README.md`, корректные названия компаний и организаций | ☐ | +| 17 | Настроена секция About, указаны темы (topics) | ☐ | +| 18 | Код соответствует принятому в сообществе стилю кодирования | ☐ | +| 19 | Имеется техническая документация (в `README.md` или на вики) | ☐ | +| 20 | В коде достаточно комментариев | ☐ | +| 21 | Комментарии к коммитам адекватны, коммиты показывают историю проекта | ☐ | +| 22 | В главной ветке адекватная история коммитов | ☐ | +| 23 | Добавление релизов | ☐ | +| 24 | Настройки репозитория | ☐ | + +## Пояснения + +1. **Лицензия** + Выбрана лицензия из числа конвенциональных, принятых в сообществе для данного типа проекта. В случае соменений, отдавайте предпочтение разрешающим лицензиям. Подсказка (но выбор должен быть осознанным): *MIT License* для примеров кода к статьям и небольших инструментов, *BSD 3-Clause License* -- для небольших библиотек и полезных утилит, *Apache License 2.0* -- для перспективных фреймворков и масштабных идей, L(GPL) v2 или даже семейство v3 -- по желанию или по ситуации. + +2. **Правильное применение лицензии** + Каждая лицензия имеет требования к тому, как её правильно применить к файлам в репозитории. Например, *Apache License 2.0* позволяет себя применять пофайлово, для чего требует включения в лицензируемые файлы стандартного заголовка. Также распространено использование файла `LICENSE` в корне репозитория и ссылка на него в заголовке каждого файла. Поищите для своей лицензии, как её правильно применять. + +3. **Совместимость сторонних компонентов** + Если используете чужую интеллектуальную собственность, найдите на неё лицензию и проверьте, что вы действительно выполняете её требования (например, проект, лицензированный под *Apache License 2.0* **не может** использовать код, лицензированный под *GPL v2*). Если чужой материал не имеет лицензии (например, просто картинка из интернета или кусок кода со Stack Overflow), использовать его **нельзя**. + +4. **Настройка CI** + Если вы используете GitHub, Continuous Integration-систему удобнее всего настраивать на *GitHub Actions*, однако вполне допустимы и сторонние системы, такие как *AppVeyor*, *CircleCI*. Если вы используете компилируемые языки, CI-система должна проверять собирабельность кода в каждой ветке репозитория и при пуллреквесте. Если интерпретируемые — проверять качество кода и работоспособность. + +5. **Тесты в CI** + В проекте должны быть регрессионные (рекомендуются даже модульные) тесты, за редкими исключениями, где они неприменимы или бессмысленны, и тесты должны запускаться в CI. + +6. **Линтер в CI** + Должен быть настроен форматтер/линтер, следящий за качеством кода, и также запускаться в CI. Если линтер выдаёт ошибки, сборка должна не проходить. + - Например, для F# линтер — это *FSharpLint*, для Python — *flake8*, форматтер для F# — это *Fantomas*, для Python — *black*. Нет ничего плохого в том, чтобы использовать форматтер и линтер в CI, настроенные так, чтобы некачественный код даже не доходил до фазы сборки. + - Запуск линтера может быть отдельной задачей в CI, чтобы не гонять его по нескольку раз в разных конфигурациях сборки. + - Имеет смысл сделать запуск линтера локальным *pre-commit hook* в git, чтобы некорректный код даже не позволяли закоммитить. Если есть возможность интегрировать среду разработки и линтер/форматтер, сделайте это. Например, *Visual Studio Code* легко подружить с *Fantomas*, чтобы он запускался при каждом сохранении файла и делал как надо. + +7. **`.gitignore`** + На GitHub файл `.gitignore` можно выбрать при создании репозитория, но также часто требуется ручная модификация. Должно быть так, чтобы все файлы, которые `.gitignore` позволяет закоммитить, реально нужно было коммитить. **В репозитории не должно быть результатов сборки** (то есть папок `bin`, `obj`, `__pycache__` и т.п.), в идеале не должно быть бинарных файлов вовсе (только если очень надо и вы реально знаете, что делаете). + +8. **Секретная информация** + Разумеется, в репозитории (включая историю коммитов) не должно быть ничего, что вы не хотели бы публиковать (например, ключей авторизации от сообществ ВКонтакте). Если пользуетесь GitHub, кое-что он умеет ловить сам, для этого надо убедиться, что в *Settings → Code security and analysis* включено *Push protection*. Но, разумеется, большую часть секретов он не найдёт. + +9. **Сторонние анализаторы** + Используйте сторонние анализаторы для слежения за качеством кода: например, *CodeCov* для анализа тестового покрытия, *CodeFactor* или *Codacy* как продвинутый статический анализатор. Чем больше инструментов следят за тем, что всё хорошо, тем лучше. + +10. **Санитайзеры для C/C++** + Языки типа С и С++ дают возможности для работы на низком уровне, но благодаря этому повышается вероятность появления таких ошибок, как небезопасная работа с памятью или *undefined behavior*. Поэтому для проектов на этих языках стоит включать санитайзеры при сборке, тестировать санитайзерами на CI, а также запускать инструменты для отслеживания утечек памяти (например, *Valgrind*). + +11. **Плашки в `README.md`** + Добавьте в `README.md` плашки CI и анализаторов (штучки, на которых написано «*CI passing*» или что-то такое). В документации конкретной CI-системы или анализатора обычно легко найти, как добавить плашку в Markdown. Это поможет посетителям сразу посмотреть статус кода. + +12. **Общее описание проекта** + Напишите в `README.md` пару абзацев текста, про что вообще проект. Помните, что код вы пишете не только для себя, в ваш репозиторий придут люди, которые вообще не имеют идей, о чём это. + +13. **Пример использования** + Опишите типичный пример использования, если уместно, с картинками или gif-ками. Включая информацию, откуда брать датасеты, куда подкладывать конфигурацию и т.п., чтобы любой пользователь мог с чистого листа запустить проект и понять, что у него получилось. + +14. **Инструкция по сборке и запуску** + Опишите также действия по сборке и внешние зависимости (версию используемых SDK и т.п.). Это всё есть в CI, но в `README` это всё должно быть в удобной человекочитаемой форме и заодно приводить к развёртыванию окружения, пригодного для работы над проектом (тогда как сборка в CI может быть весьма хитрой, использовать несколько Docker-образов и т.п.). + +15. **Как помочь проекту** + Если проект предполагает возможность стороннего участия (то есть имеет хоть один шанс стать знаменитым), опишите, как сторонний человек может вам помочь: + - куда и как писать баги; + - как связаться с разработчиками; + - как контрибьютить; + - где посмотреть техническую документацию и найти первый вводный баг, который можно поправить. + +16. **Корректные названия** + Названия каких-либо организаций, используемых инструментов или технологий должны быть написаны так же, как в официальных источниках (пример: *TRIK Studio*, а не *Trik Studio*, *RISC-V*, а не *RISC-5*). + +17. **Секция About** + Оформите секцию *About*: стоит добавить подходящие темы (*topics*), чтобы ваш репозиторий было легче найти, и описание (*description*), чтобы стороннему человеку было понятно, зачем репозиторий нужен (кратко, одним предложением — подробное описание в `README.md`). + +18. **Стиль кодирования** + Проверьте, что код в репозитории адекватно оформлен. Если на Python, то *PEP-8*, если на C++, то в соответствии с *Core Guidelines* и т.п. — у каждого языка и даже у некоторых фреймворков есть свой стиль кодирования, проверьте, что код его уважает. Если в проекте используется свой стиль кодирования, он должен быть явно задокументирован и весь код должен ему соответствовать. + +19. **Техническая документация** + Где-то должно быть некое техническое описание проекта — из каких компонентов он состоит, кто за что отвечает. В идеале — полноценная архитектурная документация в виде страниц на вики, с UML-диаграммами, но если сил нет, можно ограничиться разделом в `README`, где кратко словами всё описать. Также вместе с/вместо вики может быть уместна документация на *Read The Docs*. + +20. **Комментарии в коде** + В коде должны быть комментарии (в принятом для языка формате — *DocString*, *Doxygen*, *Javadoc*, *XML Documentation* и т.п.), хотя бы у ключевых классов/интерфейсов/модулей, кратко описывающие, что вообще делает класс. В идеале — для всего, что *public*, с документированием предположений о входных данных, инвариантов, бросаемых исключений и свойств потокобезопасности (*reentrant*, *thread-safe* и т.п.), но насколько сил хватит. + - В идеале — по комментариям в коде должна автоматически генерироваться документация и выкладываться на *GitHub Pages* или тот же *Read The Docs* (в т.ч. как действие при сборке в CI, то есть полностью автоматически). Например, для Python есть инструмент *Sphinx*, который в этом помогает. + +21. **Комментарии к коммитам** + Комментарии к коммитам пост-фактум исправить тяжело, поэтому за ними надо следить изначально. Рекомендуется следовать соглашению *Conventional Commits*. Коммиты не должны быть сделаны в последний день, а должны показывать, как шла работа, от создания пустого проекта до последнего релиза. Фразы вида «*я тут локально разрабатывал, потом выложил, как получилось что-то разумное*» очень сильно огорчают комиссию. Могут помочь инструменты типа *Mergeable*, *Mergify*. + +22. **История коммитов в main** + Почистите главную ветку репозитория от лишнего. Если у вас в репозитории больше пяти маловменяемых комментариев (типа «*fix*») подряд, либо несколько коммитов отвечают за небольшие изменения одной и той же функциональности, лучше либо сделайте *squash* и склейте коммиты в один, либо измените всю историю через `git rebase -i`. + +23. **Релизы** + Если ваш проект позиционируется как библиотека, игра или какой-либо независимый инструмент, рекомендуется публиковать новые версии в качестве релизов, т.к. они предоставляют пользователям удобный способ доступа к конкретным версиям вашего проекта и информации о том, что именно изменено или добавлено в каждой версии. Рекомендуется ознакомиться со стандартами оформления релизов и *Semantic Versioning*. + +24. **Настройки репозитория** + Рекомендуется настроить правила защиты веток (например, запретить *force push* в `main`), а также инструменты безопасности и анализа кода (обновление зависимостей через *Dependabot*, инструмент *CodeQL* для автоматического обнаружения распространенных уязвимостей и ошибок в коде). + +--- + +## Чеклист по оформлению пуллреквеста + +| № | Пункт | Выполнено | +| --- | ------- | ----------- | +| 1 | Адекватное название | ☐ | +| 2 | Описание пуллреквеста, список предлагаемых изменений (если применимо, со ссылками на закрытые issues) | ☐ | +| 3 | Описание пуллреквеста, описание работы предлагаемой функциональности (если возможно, с gif-кой демо) | ☐ | +| 4 | Описание пуллреквеста, техническое описание, изменения в архитектуре | ☐ | +| 5 | Модульные тесты на новый код | ☐ | +| 6 | CI проходит, при необходимости подредактирован, чтобы запускать новый код | ☐ | +| 7 | Содержимое пуллреквеста лицензионно совместимо с основным репозиторием | ☐ | +| 8 | Коммиты в истории следуют принятым в проекте соглашениям (отдельные или склеены в один) | ☐ | +| 9 | Стиль кодирования соответствует стилю проекта | ☐ | + +### Пояснения к чеклисту пуллреквестов + +П.3. **Демонстрация изменений** + Анимированные gif-файлы легко делаются инструментами для захвата экрана (например, *ScreenToGIF*), и очень нужны, когда делается что-то в UI (например, чтобы наглядно показать, как было → как стало). + +- Если пуллреквест что-то ускоряет, приложите графики замера времени (или *flame graphs* из вашего любимого профилятора — вы ведь не пытаетесь что-то ускорить без профилятора, да?), показывающие ускорение. +- Если пуллреквест улучшает какой-то классификатор, приложите *ROC-кривую* или что-нибудь такое. +- Если занимаетесь машинным зрением, выложите кучу наглядных скриншотов. +- Вообще, активно используйте наглядные иллюстрации того, почему именно пуллреквест должны принять. + +П.4. **Техническое описание** + Для описания архитектуры используйте UML-диаграммы (см. [uml-diagrams.org](https://www.uml-diagrams.org/) как краткий справочник по стандарту, избегайте *UML-like* картинок). Выделите цветом, что поменялось. Текстом опишите, что на диаграмме нарисовано (одна диаграмма архитектуры не описывает). + +--- + +## Полезные ссылки для любопытных + +- Правильное именование коммитов: [https://www.conventionalcommits.org/en/v1.0.0/](https://www.conventionalcommits.org/en/v1.0.0/) +- Исправление комментариев к коммитам, редактирование истории (не делайте так без крайней нужды): [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) +- Хорошее описание `.gitignore`: [https://www.atlassian.com/ru/git/tutorials/saving-changes/gitignore](https://www.atlassian.com/ru/git/tutorials/saving-changes/gitignore) +- Модели работы с ветками: + - [https://www.atlassian.com/ru/git/tutorials/comparing-workflows](https://www.atlassian.com/ru/git/tutorials/comparing-workflows) + - [https://www.gitkraken.com/learn/git/best-practices/git-branch-strategy](https://www.gitkraken.com/learn/git/best-practices/git-branch-strategy) + - [https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow](https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow) +- Зачем нужен `README.md` и как его писать: [https://bulldogjob.com/readme/how-to-write-a-good-readme-for-your-github-project](https://bulldogjob.com/readme/how-to-write-a-good-readme-for-your-github-project) +- Шаблон `README` с плашками и другими хорошими вещами: [https://github.com/othneildrew/Best-README-Template](https://github.com/othneildrew/Best-README-Template) +- Подборка примеров хороших `README`: [https://github.com/matiassingers/awesome-readme](https://github.com/matiassingers/awesome-readme) +- Генератор `README`: [https://readme.so/ru](https://readme.so/ru) +- Гайд по лицензиям от GitHub: [https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository) +- Слайды лекции про авторские права в IT от Я.А. Кириленко: [https://docs.google.com/presentation/d/1-xMvM_EyouDM9slBpQHR3h7MRgYrMQCKZ2dxYeFKh20](https://docs.google.com/presentation/d/1-xMvM_EyouDM9slBpQHR3h7MRgYrMQCKZ2dxYeFKh20) +- Может быть полезен *Dependabot* ([https://docs.github.com/en/code-security/dependabot](https://docs.github.com/en/code-security/dependabot)), для автоматического обновления внешних зависимостей в проекте. diff --git a/repo-checklist/repo-checklist-short.md b/repo-checklist/repo-checklist-short.md new file mode 100644 index 0000000..fc32a03 --- /dev/null +++ b/repo-checklist/repo-checklist-short.md @@ -0,0 +1,76 @@ + + +# Чеклист репозитория + +Короткая версия чеклиста для проверки репозиториев и PR , более полная (с дополнительными детальными пояснениями) лежит [в основном репозитории](https://github.com/spbu-se/practice-templates/tree/main/repo-checklist) + +## Основной чеклист (10 пунктов, не более) + +| № | Пункт | Выполнено | +| --- | ------- | ----------- | +| 1 | Выбрана нужная лицензия и правильно применена | ☐ | +| 2 | `README.md` с описанием, примером и инструкцией по запуску | ☐ | +| 3 | История коммитов чистая, названия коммитов понятны | ☐ | +| 4 | Настроен `.gitignore`, нет артефактов сборки и зависимостей | ☐ | +| 5 | В репозитории нет секретной информации (ключи, пароли, токены) | ☐ | +| 6 | Код следует стилю языка (PEP-8 для Python, и т.п.) | ☐ | +| 7 | Код имеет необходимые комментарии и документацию | ☐ | +| 8 | В CI настроены автоматическая проверка качества кода и регрессионное тестирование | ☐ | +| 9 | Общие замечания: названия и технологий написаны корректно | ☐ | +| 10 | Опционально: плашки, заметки о решениях и т.д. | ☐ | + +--- + +## Пояснения + +**1. Лицензия** +Выберите лицензию для своего кода, правильно примените её. Рекомендуется использовать популярные в сообществе лицензии, используемые в аналогичных ситуациях. Добавьте файл `LICENSE`/`LICENSE.md` в корень репозитория. Если репозиторий использует чужой код или библиотеки, убедитесь, что выбранная лицензия совместима. Правильно используйте лицензию (заголовок в стиле SPDX или специальная шапка, если лицензией не предполагается иное). + +**2. README.md (описание PR) и сопутствующая документация** +Напишите описание проекта или раскройте суть PR (2-3 абзаца), покажите пример использования (где уместно). Если в репозитории несколько компонентов, кратко объясните их назначение. Для проекта сделайте инструкцию по установке (установке зависимостей, сборке, запуску), для эксперимента по производительности или иной решаемой проблемы (актуально для PR) опишите способ воспроизведения. Документируйте требования по сборке (развёртыванию) и запуску. Важны конкретные команды и необходимые версии инструментов (но допустимо ссылаться на скрипты CI). + +**3. История коммитов** +Правило применяется к главной ветке представляемого проекта или к конкретному рассматриваемому PR (ветке для PR). Коммиты должны показывать логику разработки. Названия должны быть понятны (например, `"Add user authentication"`, а не `"fix"`). Рекомендуется следовать соглашению [Conventional Commits](https://www.conventionalcommits.org/). Если в ветке несколько коммитов, отвечающих за одну фичу, их можно объединить через `git rebase -i` перед merge'ем. + +**4. `.gitignore` и артефакты** +Настройте `.gitignore`, чтобы в репозитории не было результатов сборки (`bin/`, `obj/`, `__pycache__/`, `node_modules/`, `.venv/` и т.п.), временных файлов и зависимостей. В репозитории должен быть только исходный код — всё остальное должно генерироваться при сборке. + +**5. Отсутствие секретов** +Убедитесь, что в коде и истории коммитов нет никаких ключей API, паролей, токенов авторизации или прочей конфиденциальной информации. Если используете переменные окружения для секретов, добавьте пример конфига (например, `.env.example`). + +**6. Стиль кода** +Код должен соответствовать принятому в сообществе стилю для вашего языка. Например, PEP-8 для Python, LLVM Coding Standards для C++ и т.п. Используйте форматтер и линтер (например, `black`/`flake8`/`ruff` для Python, `clang-format` для C++) локально перед коммитом. + +**7. Комментарии** +Добавьте комментарии к функциям и классам (в стиле DocString, JSDoc, Doxygen и т.п.), объясняющие, что они делают для нетривиальной логики. Ставьте себя на место другого разработчика — ему должно быть понятно, зачем нужна каждая часть кода. + +**8. Автоматизация проверок: тесты и CI** +Автоматизируйте проверку качества кода (линтеры и форматтеры, статические анализаторы, опции компилятора). Напишите тесты для регрессионного тестирования (предпочитайте модульные тесты). Используйте предоставляемые языком (компилятором, библотеками) дополнительные возможности проверки корректности при исполнении (санитайзеры, опции интерпретатора). Настройте CI так, чтобы проверки и регрессионные тесты запускались при каждом push'е и pull request'е. Сборка должна не проходить, если тесты падают или есть ошибки стиля кода. + +**9. Общие рекомендации** +_Это пункт с перечнем типовых недочётов, обязательно выполнить._ + +* Везде (обязательно в коде и в документации) названия организаций, инструментов, технологий должны быть написаны так же, как в официальных источниках. Примеры: RISC-V (не RISC-5), OpenGL (не OpenGl), GitHub (не Github). + +**10. Дополнительно** +_Можно использовать дополнительные возможности проявить себя._ + +* **Плашки CI и анализаторов** — полезно для проекта, уместно в README. +* **Architectural Decision Records (ADR)** — краткие документы, объясняющие, почему вы выбрали ту или иную технологию, алгоритм или структуру данных. Это помогает понять, что проект не «слепая» копипаста, а обдуманный дизайн. +* **`CHANGELOG.md`** — стандартный файл с перечнем изменений по версиям, полезно даже для учебных проектов; формат можно взять с [Keep a Changelog](https://keepachangelog.com/). +* **benchmark**/**performace notes** — если вы писали простые замеры (например, сравнение скорости нескольких реализаций), положите их в репозиторий вместе с инструкциями воспроизведения. +* **issues** / **project board** в проекте — демонстрация, что вы умеете разбивать работу на задачи, использовать метки (good‑first‑issue, bug, enhancement) и закрывать их по мере выполнения. +Выберите один или несколько вариантов. Главное — показать, что проект ведётся формально, с документированием мыслей и изменений, а не только набором файлов. + +--- + +## Бонус: полезные идеи при оформлении, дают доплнительные баллы при проверке + +* **Архитектура**: если в README добавить краткое описание структуры проекта (какие файлы/папки за что отвечают), разбирающему будет проще. Можно сделать отдельный `ARCHITECTURE.md`, добавить в него схему и описания компонентов. +* **Примеры**: отдельная папка `examples/` с работающим кодом очень помогает. +* **Документирование ошибок**: если есть известные ограничения или баги, про них лучше написать в README, чем скрывать, а на GitHub и подобных ресурсах можно занести в issues и дать ссылку. +* **Версионирование**: используйте [Semantic Versioning](https://semver.org/) (major.minor.patch) и добавляйте теги в Git при релизе. +* **Релиз для проверки**: опубликуйте релиз, соответствующий состоянию представляемой на контроль работы (для PR -- сделайте PR в основной проект, а не просто ветку для проверки) diff --git a/repo-checklist/repo-checklist.pdf b/repo-checklist/repo-checklist.pdf deleted file mode 100644 index d215ad1..0000000 Binary files a/repo-checklist/repo-checklist.pdf and /dev/null differ diff --git a/repo-checklist/repo-checklist.tex b/repo-checklist/repo-checklist.tex deleted file mode 100644 index bc3bd5f..0000000 --- a/repo-checklist/repo-checklist.tex +++ /dev/null @@ -1,152 +0,0 @@ -\documentclass[a5paper]{article} -\usepackage[a5paper, top=8mm, bottom=8mm, left=8mm, right=8mm]{geometry} - -\usepackage{polyglossia} -\setdefaultlanguage[babelshorthands=true]{russian} - -\usepackage{fontspec} -\setmainfont{FreeSerif} -\newfontfamily{\russianfonttt}[Scale=0.7]{DejaVuSansMono} - -\usepackage[font=scriptsize]{caption} - -\PassOptionsToPackage{hyphens}{url}\usepackage[xetex,linktocpage=true,plainpages=false,pdfpagelabels=false]{hyperref} -\hypersetup{colorlinks=true, linkcolor=blue, citecolor=blue, filecolor=blue, urlcolor=blue, pdftitle=1, pdfauthor=, pdfsubject=, pdfkeywords=} - -\usepackage{tabu} - -\tabulinesep=1.2mm - -\sloppy - -\pagestyle{plain} - -\title{Чеклист по оформлению репозитория} - -\begin{document} - -\maketitle - -\section*{Чеклист по оформлению репозитория} - -\begin{tabu} {| X[0.1 l p] | X[2 l p] | X[0.1 l p] |} - \tabucline- - \everyrow{\tabucline-} - 1 & Лицензия & \\ - 2 & Лицензия правильно применяется к репозиторию & \\ - 3 & Используемые третьесторонние компоненты и материалы совместимы с лицензией & \\ - 4 & Настроенный CI & \\ - 5 & Модульные тесты в CI & \\ - 6 & Линтер в CI & \\ - 7 & В репозитории нет результатов сборки, настроен .gitignore & \\ - 8 & В репозитории нет секретной информации (паролей, ключей и т.п.) & \\ - 9 & Различные сторонние анализаторы (если уместно) & \\ - 10 & Для кода на С/С++: использование санитайзеров & \\ - 11 & README.md, плашки CI и анализаторов & \\ - 12 & README.md, общее описание проекта & \\ - 13 & README.md, пример использования & \\ - 14 & README.md, инструкция по сборке и запуску & \\ - 15 & README.md, как помочь проекту (если уместно) & \\ - 16 & README.md, корректные названия компаний и организаций & \\ - 17 & Настроена секция About, указаны темы (topics) & \\ - 18 & Код соответствует принятому в сообществе стилю кодирования & \\ - 19 & Имеется техническая документация (в README.md или на вики) & \\ - 20 & В коде достаточно комментариев & \\ - 21 & Комментарии к коммитам адекватны, коммиты показывают историю проекта & \\ - 22 & В главной ветке адекватная история коммитов & \\ - 23 & Добавление релизов & \\ - 24 & Настройки репозитория & \\ -\end{tabu} - -\section*{Пояснения} - -\begin{enumerate} - \item Отдавайте предпочтение разрешающим лицензиям. Код мы рекомендуем лицензировать под Apache License 2.0, MIT License, BSD 3-Clause License. - \item Каждая лицензия имеет требования к тому, как её правильно применить к файлам в репозитории. Например, Apache License 2.0 позволяет себя применять пофайлово, для чего требует включения в лицензируемые файлы стандартного заголовка. Также распространено использование файла LICENSE в корне репозитория и ссылка на него в заголовке каждого файла. Поищите для своей лицензии, как её правильно применять. - \item Если используете чужую интеллектуальную собственность, найдите на неё лицензию и проверьте, что вы действительно выполняете её требования (например, проект, лицензированный под Apache License 2.0 \emph{не может} использовать код, лицензированный под GPL v2). Если чужой материал не имеет лицензии (например, просто картинка из интернета или кусок кода со Stack Overflow), использовать его \emph{нельзя}. - \item Если вы используете GitHub, Continuous Integration-систему удобнее всего настраивать на GitHub Actions, однако вполне допустимы и сторонние системы, такие как AppVeyor, CircleCI. Если вы используете компилируемые языки, CI-система должна проверять собирабельность кода в каждой ветке репозитория и при пуллреквесте. Если интерпретируемые, проверять качество кода и работоспособность. - \item В проекте должны быть модульные тесты (за редкими исключениями, где они неприменимы или бессмысленны), и модульные тесты должны запускаться в CI. - \item Должен быть настроен форматтер/линтер, следящий за качеством кода, и также запускаться в CI. Если линтер выдаёт ошибки, сборка должна не проходить. - \begin{itemize} - \item Например, для F\# линтер --- это FSharpLint, для Python --- flake8, форматтер для F\# --- это Fantomas, для Python --- black. Нет ничего плохого в том, чтобы использовать форматтер и линтер в CI, настроенные так, чтобы некачественный код даже не доходил до фазы сборки. - \item Запуск линтера может быть отдельной задачей в CI, чтобы не гонять его по нескольку раз в разных конфигурациях сборки. - \item Имеет смысл сделать запуск линтера локальным pre-commit hook в git, чтобы некорректный код даже не позволяли закоммитить. Если есть возможность интегрировать среду разработки и линтер/форматтер, сделайте это. Например, Visual Studio Code легко подружить с Fantomas, чтобы он запускался при каждом сохранении файла и делал как надо. - \end{itemize} - \item На GitHub файл .gitignore можно выбрать при создании репозитория, но также часто требуется ручная модификация. Должно быть так, чтобы все файлы, которые .gitignore позволяет закоммитить, реально нужно было коммитить. \emph{В репозитории не должно быть результатов сборки,} (то есть папок bin, obj, pycache и т.п.), в идеале не должно быть бинарных файлов вовсе (только если очень надо и вы реально знаете, что делаете). - \item Разумеется, в репозитории (включая историю коммитов) не должно быть ничего, что вы не хотели бы публиковать (например, ключей авторизации от сообществ ВКонтакте). Если пользуетесь GitHub, кое-что он умеет ловить сам, для этого надо убедиться, что в <> включено <>. Но, разумеется, большую часть секретов он не найдёт. - \item Используйте сторонние анализаторы для слежения за качеством кода: например, CodeCov для анализа тестового покрытия, CodeFactor или Codacy как продвинутый статический анализатор. Чем больше инструментов следят за тем, что всё хорошо, тем лучше. - \item Языки типа С и С++ дают возможности для работы на низком уровне, но благодаря этому повышается вероятность появления таких ошибок, как небезопасная работа с памятью или undefined behavior. Поэтому для проектов на этих языках стоит включать санитайзеры при сборке, тестировать санитайзерами на CI, а также запускать инструменты для отслеживания утечек памяти (например, Valgrind). - \item Добавьте в README.md плашки CI и анализаторов (штучки, на которых написано <> или что-то такое). В документации конкретной CI-системы или анализатора обычно легко найти, как добавить плашку в Markdown. Это поможет посетителям сразу посмотреть статус кода. - \item Напишите в README.md пару абзацев текста, про что вообще проект. Помните, что код вы пишете не только для себя, в ваш репозиторий придут люди, которые вообще не имеют идей, о чём это. - \item Опишите типичный пример использования, если уместно, с картинками или gif-ками. Включая информацию, откуда брать датасеты, куда подкладывать конфигурацию и т.п., чтобы любой пользователь мог с чистого листа запустить проект и понять, что у него получилось. - \item Опишите также действия по сборке и внешние зависимости (версию используемых SDK и т.п.). Это всё есть в CI, но в README это всё должно быть в удобной человекочитаемой форме и заодно приводить к развёртыванию окружения, пригодного для работы над проектом (тогда как сборка в CI может быть весьма хитрой, использовать несколько Docker-образов и т.п.). - \item Если проект предполагает возможность стороннего участия (то есть имеет хоть один шанс стать знаменитым), опишите, как сторонний человек может вам помочь: - \begin{itemize} - \item куда и как писать баги; - \item как связаться с разработчиками; - \item как контрибьютить; - \item где посмотреть техническую документацию и найти первый вводный баг, который можно поправить. - \end{itemize} - \item Названия каких-либо организаций, используемых инструментов или технологий должны быть написаны так же, как в официальных источниках (пример: TRIK Studio, а не Trik Studio, RISC-V, а не RISC-5). - \item Оформите секцию About: стоит добавить подходящие темы (topics), чтобы ваш репозиторий было легче найти, и описание (description), чтобы стороннему человеку было понятно, зачем репозиторий нужен (кратко, одним предложением --- подробное описание в README.md). - \item Проверьте, что код в репозитории адекватно оформлен. Если на Python, то PEP-8, если на C++, то в соответствии с Core Guidelines и т.п. --- у каждого языка и даже у некоторых фреймворков есть свой стиль кодирования, проверьте, что код его уважает. Если в проекте используется свой стиль кодирования, он должен быть явно задокументирован и весь код должен ему соответствовать. - \item Где-то должно быть некое техническое описание проекта --- из каких компонентов он состоит, кто за что отвечает. В идеале --- полноценная архитектурная документация в виде страниц на вики, с UML-диаграммами, но если сил нет, можно ограничиться разделом в README, где кратко словами всё описать. Также вместе с/вместо вики может быть уместна документация на Read The Docs. - \item В коде должны быть комментарии (в принятом для языка формате --- DocString, Doxygen, Javadoc, XML Documentation и т.п.), хотя бы у ключевых классов/интерфейсов/модулей, кратко описывающие, что вообще делает класс. В идеале --- для всего, что public, с документированием предположений о входных данных, инвариантов, бросаемых исключений и свойств потокобезопасности (reentrant, thread-safe и т.п.), но насколько сил хватит. - \begin{itemize} - \item В идеале --- по комментариям в коде должна автоматически генерироваться документация и выкладываться на GitHub Pages или тот же Read The Docs (в т.ч. как действие при сборке в CI, то есть полностью автоматически). Например, Для Python есть инструмент Sphinx, который в этом помогает. - \end{itemize} - \item Комментарии к коммитам пост-фактум исправить тяжело, поэтому за ними надо следить изначально. Рекомендуется следовать соглашению Conventional Commits. Коммиты не должны быть сделаны в последний день, а должны показывать, как шла работа, от создания пустого проекта до последнего релиза. Фразы вида <<я тут локально разрабатывал, потом выложил, как получилось что-то разумное>> очень сильно огорчают комиссию. Могут помочь инструменты типа Mergeable, Mergify. - \item Почистите главную ветку репозитория от лишнего. Если у вас в репозитории больше пяти маловменяемых комментариев (типа «fix») подряд, либо несколько коммитов отвечают за небольшие изменения одной и той же функциональности, лучше либо сделайте squash и склейте коммиты в один, либо измените всю историю через git rebase -i. - \item Если ваш проект позиционируется как библиотека, игра или какой-либо независимый инструмент, рекомендуется публиковать новые версии в качестве релизов, т.к. они предоставляют пользователям удобный способ доступа к конкретным версиям вашего проекта и информации о том, что именно изменено или добавлено в каждой версии. Рекомендуется ознакомиться со стандартами оформления релизов и Semantic versioning. - \item Рекомендуется настроить правила защиты веток (например, запретить force push в main), а также инструменты безопасности и анализа кода (обновление зависимостей через Dependabot, инструмент CodeQL для автоматического обнаружения распространенных уязвимостей и ошибок в коде). -\end{enumerate} - -\section*{Чеклист по оформлению пуллреквеста} - -\begin{tabu} {| X[0.1 l p] | X[2 l p] | X[0.1 l p] |} - \tabucline- - \everyrow{\tabucline-} - 1 & Адекватное название & \\ - 2 & Описание пуллреквеста, список предлагаемых изменений (если применимо, со ссылками на закрытые issues) & \\ - 3 & Описание пуллреквеста, описание работы предлагаемой функциональности (если возможно, с gif-кой демо) & \\ - 4 & Описание пуллреквеста, техническое описание, изменения в архитектуре & \\ - 5 & Модульные тесты на новый код & \\ - 6 & CI проходит, при необходимости подредактирован, чтобы запускать новый код & \\ - 7 & Содержимое пуллреквеста лицензионно совместимо с основным репозиторием & \\ - 8 & Коммиты в истории следуют принятым в проекте соглашениям (отдельные или склеены в один) & \\ - 9 & Стиль кодирования соответствует стилю проекта & \\ -\end{tabu} - -\section*{Пояснения} - -\begin{enumerate} - \setcounter{enumi}{2} - \item Анимированные gif-файлы легко делаются инструментами для захвата экрана (например, ScreenToGIF), и очень нужны, когда делается что-то в UI (например, чтобы наглядно показать, как было --- как стало). - \begin{itemize} - \item Если пуллреквест что-то ускоряет, приложите графики замера времени (или flame graphs из вашего любимого профилятора --- вы ведь не пытаетесь что-то ускорить без профилятора, да?), показывающие ускорение. Если пуллреквест улучшает какой-то классификатор, приложите ROC-кривую или что-нибудь такое. Если занимаетесь машинным зрением, выложите кучу наглядных скриншотов. Вообще, активно используйте наглядные иллюстрации того, почему именно пуллреквест должны принять. - \end{itemize} - \item Для описания архитектуры используйте UML-диаграммы (см. \url{https://www.uml-diagrams.org/} как краткий справочник по стандарту, избегайте UML-like картинок). Выделите цветом, что поменялось. Текстом опишите, что на диаграмме нарисовано (одна диаграмма архитектуру не описывает). -\end{enumerate} - -\section*{Полезные ссылки для любопытных} - -\begin{itemize} - \item Правильное именование коммитов: \url{https://www.conventionalcommits.org/en/v1.0.0/}. - \item Исправление комментариев к коммитам, редактирование истории (не делайте так без крайней нужды): \url{https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History}. - \item Хорошее описание .gitignore: \url{https://www.atlassian.com/ru/git/tutorials/saving-changes/gitignore}. - \item Модели работы с ветками: - \begin{itemize} - \item \url{https://www.atlassian.com/ru/git/tutorials/comparing-workflows}; - \item \url{https://www.gitkraken.com/learn/git/best-practices/git-branch-strategy}; - \item \url{https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow}. - \end{itemize} - \item Зачем нужен README.md и как его писать: \url{https://bulldogjob.com/readme/how-to-write-a-good-readme-for-your-github-project}. - \item Шаблон README с плашками и другими хорошими вещами: \url{https://github.com/othneildrew/Best-README-Template}. - \item Подборка примеров хороших README: \url{https://github.com/matiassingers/awesome-readme}. - \item Генератор README: \url{https://readme.so/ru}. - \item Гайд по лицензиям от GitHub: \url{https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository}. - \item Слайды лекции про авторские права в IT от Я.А. Кириленко: \url{https://docs.google.com/presentation/d/1-xMvM_EyouDM9slBpQHR3h7MRgYrMQCKZ2dxYeFKh20}. - \item Может быть полезен dependabot (\url{https://docs.github.com/en/code-security/dependabot}), для автоматического обновления внешних зависимостей в проекте. -\end{itemize} - -\end{document} \ No newline at end of file