Skip to content

Development

Jump to bottom
vs9h edited this page Aug 13, 2023 · 8 revisions

Полезная информация для разработки

Работа с GitHub

Общие мысли

  • Мы форкаем, а не работаем напрямую с оригиналом, чтобы не было страшно что-то сломать (GitHub не даёт возможности за бесплатно защитить main).
  • Мы стараемся поддерживать линейную историю -- для этого нужно использовать rebase при разрешении конфликтов.
  • Мы придерживаемся trunk-based development.

Как работаем

  1. Инициализация

    1. Заходим в https://github.com/Mstrutov/Desbordante → нажимаем fork
    2. Клонируем к себе на ПК, создаём новую ветку 
      git clone https://github.com/<Ваш ник>/Desbordante
git checkout -b <new_feature>
      (Дальше с кодом можно делать что угодно, оригинальный репозиторий не будет затронут. В любом случае, при попытке push в Mstrutov/Desbordante будет permission denied)

  2. Настроить fetch. Git на ПК не знает, что работает с форком — надо ему дать ссылку на оригинал.

    git remote add upstream https://github.com/Mstrutov/Desbordante
git remote -v

    Последней строчкой глазами проверили, что есть два внешних репозитория: оригинал (upstream) и форк (origin)

  3. Подтянуть изменения, если некий Программист успел своевременно поменять код в Mstrutov/Desbordante/main

    git pull --rebase upstream main

    Под капотом происходит:

    git fetch upstream — узнать состояние upstream репы
git checkout main — перейти в свой main
git rebase upstream/main — ребазировать свой main на upstream/main

    Это нужно делать, чтобы поддерживать свой форк в синхронизации с оригиналом — иначе будут большие сложности с финальным добавлением алгоритма.

    Можно настроить rebase по умолчанию, тогда можно будет писать просто git pull:

    git config --global pull.rebase preserve

  4. Рабочий цикл (коммит-пуш)

    ... do stuff ...
git add <done stuff>
git commit
git push origin <new_feature>

  5. Когда код собирается, работает и протестирован:

    1. Ещё раз подтянуть изменения, чтобы не было проблем при создании Pull Request (PR).
    2. Идти контрибьютить в оригинальный репо: 
      Mstrutov/Desbordante 
→ Pull requests
→ Create pull request
→ compare across forks 
→ будем добавлять <ваш форк> - new_feature в Mstrutov/Desbordante - main.
    3. Прохождение CI
    4. Код-ревью
    5. Rebase and merge

Оформление коммитов

Можно почитать здесь о том, как и зачем оформлять. Самое важное:

  • Название коммита от его тела отделяется пустой строкой;
  • В названии коммита должно быть около 50 символов или меньше;
  • Название коммита пишется с большой буквы;
  • Название коммита не должно заканчиваться точкой;
  • Название коммита пишется в повелительном наклонении (imperative mood);
  • В теле коммита строчки должны быть длиной не более 72 символов;
  • В теле коммита необходимо описать какие и зачем были сделаны изменения, а не как.

То есть, текстовое сообщение к коммиту должно выглядеть примерно так:

Summarize changes in around 50 characters or less

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Особое внимание стоит обратить на то, что в теле коммита нужно делать упор на то какие и зачем были сделаны изменения, а не как (пункт 7). При этом тело коммита само по себе не обязательно, его можно опустить, если изменения и их цель очевидна из названия.

Пример оформления коммита:

Add lock to FDAlgorithm::registerFD 

Each algorithm that supports parallelism (for now it is basically all
algorithms) has its own overrided thread-safe registerFD. To avoid such
code duplication add mutex to FDAlgorithm and lock it in registerFD.
This approach may slow down single-threaded algorithms a bit, but I
believe fd registration is not a bottleneck, so it won't be noticeable.

Оформление пул-реквестов

Оформление пул-реквестов похоже на оформление коммитов. В названии пул-реквеста необходимо кратко описать выжимку из того, что делают коммиты в нем. В описании нужно написать более подробно какие изменения принятый пул-реквест привнесет. Также следует использовать issues linking для issues, которые данный пул-реквест исправляет. Либо, если таких нет, то стоит описать, какую проблему пул-реквест решает (то есть зачем он был сделан).

Полезные ссылки

Требования к оформлению бумаги (курсовой)

Книжка по плюсам

C++ style guide

По умолчанию нужно следовать Google C++ style guide, за некоторыми исключениями.

Исключения из Google C++ style guide:

  • Длина строки 100 символов;
  • Разрешено использовать исключения (exceptions);
  • Разрешены числовые встроенные типы (не только int, но и все остальные);
  • Табы по 4 (влияет на форматирование switch-case и отступы для модификаторов доступа, смотри .clang-format);
  • Расширение у С++ файлов cpp (вместо cc);
  • Разрешено #pragma once вместо стандартных include guards;
  • Файлы и директории именуются используя snake_case;
  • Порядок секций модификаторов доступа в определении класса: private, protected, public;
  • Наверняка много чего еще... (WIP)

Комментарии по основным директориям.

Что может понадобиться:

  • model -- структуры данных для базового представления таблицы
  • util -- более узкие структуры данных, на которые опираются алгоритмы

Что понадобится с меньшей вероятностью:

  • algorithms -- основная логика алгоритмов
  • core -- тут лежит более низкоуровневая логика Pyro
  • caching -- относится к Pyro, нигде не используется
  • custom -- тут ре-реализуются штуки из стандартной библиотеки для корректного сравнения с джавой
  • parser -- парсер .csv
  • logging -- тут лежит взятый снаружи логгер, его не надо трогать
Clone this wiki locally