Quick start: как начать проект с нуля

Данный гайд предполагает работу с GitHub

1. Создайте новый репозиторий

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

При создании репозитория необходимо:

• выбрать имя проекта:
  • имя должно легко запоминаться, и если возможно, давать хотя бы минимальное представление о вашем проекте;
  • нужно проверить, что нет конфликтов имен;
  • как пример - “FEDOT is a framework for automated modeling and machine learning (AutoML) problems.”
• выбрать тип лицензии:
  • использование лицензии с открытым исходным кодом обеспечивает возможность другим людям свободно использовать, копировать, изменять и вносить свой вклад в ваш проект без каких-либо юридических последствий;
  • при запуске проекта с открытым исходным кодом нужно выбрать лицензию, например BSD-3-Clause license;
  • при создании репозитория можно выбрать опцию “Choose a license” для выбора лицензии перед инициализацией репозитория.

2. Создайте нулевую версию README

В README.md можно включить краткое описание проекта, инструкции по установке и использованию. Рекомендуется использовать следующую структуру (многие из пунктов невыполнимы на начальном этапе и дополняются в будущем):

• название проекта/решения;
• логотип проекта/решения (если есть);
• информацию о проекте/решении: назначение, основные особенности, преимущества («почему стоит использовать решение?»), алгоритмы/модели (с использованием слов и изображений);
• демо: изображения, ссылки на видео, интерактивные демо-ссылки, гифки;
• техническое описание проекта (установка, настройка, как помочь проекту);
• минимальные работающие примеры кода;
• ссылка на сайт или страницу с документацией;
• ссылки на статьи (для цитирования).

При создании репозитория на GitHub можно выбрать опцию “Add a README file”, чтобы создать пустой файл README.md.

3. Настройте .gitignore

В файле .gitignore вы можете указать, какие файлы или каталоги не следует отслеживать Git. Обычно указываются временные файлы, сгенерированные средой разработки, файлы с тяжеловесными данными, или же файлы, которые содержат конфиденциальную информацию.

При создании репозитория на GitHub можно выбрать опцию “Add .gitignore”, чтобы выбрать шаблон, содержащий нежелательные файлы конкретного языка или конкретной технологии.

4. Создайте типовые задачи

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

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

• Настройка среды разработки (IDE, текстовый редактор);
• Настройка и установка зависимостей;
• Написание кода;
• Написание тестов;
• Документирование кода.

Для создания типовых задач необходимо выполнить следующие действия:

1. Откройте раздел Issues на странице вашего репозитория;
2. Нажмите кнопку “New” для создания новой задачи;
3. Задайте заголовок для задачи и опишите ее в поле “Comment”;
4. Назначьте ответственных за выполнение задачи (Assignees) участников при необходимости;
5. Добавьте метки (Labels), которые нужны для указания типа задачи, расставления приоритета задачи и других характеристик;
6. Нажмите кнопку “Submit new issue”, для создания задачи;

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

5. Настройте защиту master-ветки

Настройка защиты master ветки позволяет предотвратить случайное, нежелательное, или несанкционированное изменение в главной ветке проекта.

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

1. Перейти в настройки репозитория и выбрать “Branches” в разделе “Code and automation”.
2. В разделе “Branch protection rules” добавить правило, нажав на кнопку “Add branch protection rule”.
3. В поле “Branch name pattern” ввести “master”/”main”
4. Настройте различные параметры защиты, например “Require a pull request before merging”, “Require status checks to pass before merging”.
5. Нажмите на кнопку “Create” для сохранения правила защиты.

Также можно установить более строгие настройки PR-ов: в разделе Settings деактивировать “Allow merge commits” и “Allow rebase merging”, оставив лишь “Allow squash merging” - для обеспечения большей лаконичности master-ветки с помощью склеивания всех коммитов в PR-е в один.

6. Настройте PEP8-бота

PEP 8 (Python Enhanced Proposal) - общепринятый стиль написания кода на языке Python.

PEP8-бот предназначен для проверки вашего кода на соответствие стандарту кодирования PEP8 и предотвращению ошибок в вашем коде.

Гайд по добавлению бота к репозиторию

7. Создайте модули проекта

После создания базовой структуры проекта, содержащую README.md, LICENSE, .gitignore, создайте модули, которые необходимы для вашего проекта.

Примеры часто создаваемых модулей:

• Модуль инициализации. Данный модуль содержит код, который будет выполнен при инициализации проекта. Здесь может быть определение переменных окружения и т. д.
  • init_db.py - содержит код для инициализации базы данных при запуске приложения
• Модуль с конфигурационными настройками. Данный модуль содержит настройки проекты, которые изменяются в зависимости от условий. Это могут быть, например данные для аутентификации и. т. д.
  • auth_config.py - содержит данные для аутентификации пользователей
• Модуль с общими утилитами. Данный модуль содержит функции и классы, которые могут использоваться в других частях проекта.
  • data_utils.py - содержит функции для обработки данных, например, функцию для очистки текстовых данных
• Модуль с тестами. Данный модуль содержит различные тесты, которые позволят проверить то, насколько корректно работают разные части проекта.
  • test_models.py - содержит тесты для моделей в приложении
• Модуль с документацией. Данный модуль хранятся файлы с описанием API, инструкциями по установке, настройке, и использованию проекта.
  • api_docs.py - содержит файлы с описанием API для разработчиков
  • user_guide.py - содержит инструкции по установке, настройке и использованию для пользователей
• Модуль с примерами использования. Данный модуль содержит примеры использования различных классов или функций API, что может помочь пользователи быстрее понять, как нужно использовать проект.
  • example_api_requests.py - содержит примеры запросов к API с комментариями
  • example_config.py - содержит примеры настроек в конфигурационном файле
• Модуль для публикации. Данный модуль в будущем будет загружен в PyPI. Этот модуль может содержать функции, классы, зависимости, связанные с проектом.
  • setup.py - содержит информацию о проекте, его зависимостях и другую метаинформацию
  • requirements.txt - содержит список зависимостей, необходимых для установки для успешной работы

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

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

8. Настройте CI/CD

Continuous Integration and Continuous Delivery (CI/CD) автоматизируют разработку, тестирование и развёртывание приложения. Это помогает быстро определять проблемы/ошибки в коде и автоматически развертывать новую версию приложения.

Чтобы настроить CI/CD, вам может потребоваться создать файлы конфигурации, такие как .github/workflows, и настроить тесты, сборку и развертывание вашего проекта.

[Ссылка на гайд] - Work in progress

Return to Homepage