Шаблон каталога курса для студентов

Скачать репозиторий

git clone --recursive https://github.com/yamadharma/course-directory-student-template.git

Основные идеи

• Стандартные соглашения об именах
• Стандартное соглашение для путей к файлам
• Стандартная настройка курса внутри шаблона курса

Используемые стандарты и программные продукты

• Стандарт Git Flow.
• Стандарт Семантическое версионирование.
• Стандарт Общепринятые коммиты.

Дополнительное программное обеспечение

Средства разработки

Fedora

• Установите средства разработки:

  sudo dnf -y group install development-tools

Quarto

Установка

1. Windows

   • Chocolatey (см. Пакетный менеджер для Windows. Chocolatey):

     choco install quarto

2. Linux

   1. Linux в общем

      • Установка с помощью скрипта:

        #!/bin/bash
        
        ## Система
        TARGET=/opt
        TARGET_BIN=/usr/local/bin
        ## Домашний каталог
        # TARGET=~/opt
        # TARGET_BIN=~/.local/bin
        
        
        ## Получить тег
        TAG=`basename $(curl -sL -o /dev/null -w %{url_effective} https://github.com/quarto-dev/quarto-cli/releases/latest)`
        TAG=${TAG/v/}
        
        ## Скачать
        cd /tmp
        wget https://github.com/quarto-dev/quarto-cli/releases/download/v${TAG}/quarto-${TAG}-linux-amd64.tar.gz
        
        ## Распаковать
        mkdir -p ${TARGET}
        tar -C ${TARGET} -xvzf /tmp/quarto-${TAG}-linux-amd64.tar.gz
        mv ${TARGET}/quarto-${TAG} ${TARGET}/quarto
        
        ## Симлинк на исполняемый файл
        mkdir -p ${TARGET_BIN}
        ln -s ${TARGET}/quarto/bin/quarto ${TARGET_BIN}/quarto

   2. Gentoo

      • Gentoo, репозиторий karma:

        emerge quarto

   3. Arch

      • Arch linux:

        pacman -S quarto-cli-bin

      • Manjaro linux:

        pamac install quarto-cli-bin

   4. Fedora

      • Установка из CORP:

        sudo dnf -y copr enable iucar/rstudio
        sudo dnf -y install quarto
        sudo dnf -y install libxcrypt-compat

Общепринятые коммиты

Установка Node.js

• На Node.js базируется программное обеспечение для семантического версионирования и общепринятых коммитов.

• Для управления пакетами лучше использовать pnpm, но можно и yarn.

• Gentoo

  • Node.js:

    emerge nodejs
    emerge yarn

  • pnpm ставим из оверлея guru:

    eselect repository enable guru
    emerge --sync guru
    emerge pnpm-bin

• Ubuntu

  apt-get install nodejs
  apt-get install yarn

• Fedora

  sudo dnf -y install nodejs
  sudo dnf -y install yarn pnpm

• Windows

  • Chocolatey:

    choco install nodejs
    choco install yarn
    choco install pnpm

• MacOS

  brew install node

Настройка Node.js

Для работы с Node.js добавим каталог с исполняемыми файлами, устанавливаемыми пакетным менеджером, в переменную PATH.

• Linux
  • pnpm

    • Запустите:

      pnpm setup

    • Перелогиньтесь, или выполните:

      source ~/.bashrc

  • yarn

    • В файле ~/.bashrc добавьте к переменной PATH:

      PATH=~/.yarn/bin:$PATH
      

Установка git-flow

• Linux

  • Gentoo

    emerge dev-vcs/git-flow

  • Ubuntu

    apt-get install git-flow

  • Fedora

    • Устанавливается из COPR:

      sudo dnf -y copr enable elegos/gitflow
      sudo dnf install gitflow

• Windows Git-flow входит в состав пакета git.

  choco install git

• MacOS

  brew install git-flow

Общепринятые коммиты

1. commitizen

   • Данная программа используется для помощи в форматировании коммитов.

     • pnpm:

       pnpm add -g commitizen

     • yarn:

       yarn global add commitizen

   • При этом устанавливается скрипт git-cz, который мы и будем использовать для коммитов.

2. standard-version

   • Данная программа автоматизирует изменение номера версии.

     • pnpm:

       pnpm add -g standard-version

     • yarn:

       yarn global add standard-version

Общие правила

• Для именования каталогов и файлов будем использовать соглашение Denote.

• Рабочее пространство по предмету располагается в следующей иерархии:

  ~/work/study/
  └── <учебный год>/
      └── <учебный год>==<код предмета>/

• Например, для 2025-2026 учебного года (второй семестр) и предмета «Операционные системы» (код предмета os-intro) структура каталогов примет следующий вид:

  ~/work/study/
  └── 2026-1/
      └── 2026-1==os-intro/

• Название проекта на хостинге git имеет вид:

  <учебный год>--study--<код предмета>
  

• Например, для 2025-2026 учебного года и предмета «Операционные системы» (код предмета os-intro) название проекта примет следующий вид:

  2026-1--study--os-intro
  

• Каталог для лабораторных работ имеет вид labs.

• Каталоги для лабораторных работ имеют вид lab<номер>, например: lab01, lab02 и т.д.

• Каталог для групповых проектов имеет вид group-project.

• Каталог для персональных проектов имеет вид personal-project.

• Каталог для внешнего курса имеет вид external-course.

• Если проектов несколько, то они нумеруются подобно лабораторным работам.

• Этапы проекта обозначаются как stage<номер>.

Шаблон для рабочего пространства

• Репозиторий: https://github.com/yamadharma/course-directory-student-template.

Сознание репозитория курса на основе шаблона

• Репозиторий на основе шаблона можно создать либо вручную, через web-интерфейс, либо с помощью утилит gh.

Создание с помощью утилит

• Создание выглядит следующим образом:

  gh repo create <new-repo-name> --template="<owner/template-repo>"

• Например, для 2024-2025 учебного года и предмета «Операционные системы» (аббревиатура предмета — os-intro) создание репозитория примет следующий вид:

  mkdir -p ~/work/study/2026-1/2026-1==study--os-intro
  cd ~/work/study/2026-1/2026-1==study--os-intro
  gh repo create 2026-1--study--os-intro --template=yamadharma/course-directory-student-template --public
  git clone --recursive [email protected]:<owner>/2026-1--study--os-intro.git

Создание вручную

• Сделать свой репозиторий на основе шаблона можно и вручную: https://docs.github.com/ru/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template.

Структура шаблона

• Посмотреть доступные цели make:

  make help

• Посмотреть список доступных курсов:

  make list

• При создании структуры название курса берётся из следующих мест:

  • название курса находится в файле COURSE;
  • каталог курса называется как аббревиатура курса.

Настройка каталога курса

• Перейдите в каталог курса:

  cd ~/work/study/2026-1/2026-1==study--os-intro/2026-1--study--os-intro

• Создайте необходимые каталоги:

  echo os-intro > COURSE
  make prepare

• Отправьте файлы на сервер:

  git add .
  git commit -am 'feat(main): make course structure'
  git push

Использование git flow

• Будем использовать для работы git flow.

Конфигурация git-flow

• Инициализируем git-flow

  git flow init

  Префикс для ярлыков установим в v.

• Проверьте, что Вы на ветке develop:

  git branch

• Загрузите весь репозиторий в хранилище:

  git push -u --all

• Создадим релиз с версией 1.0.0

  git flow release start 1.0.0

• Создадим журнал изменений

  standard-changelog --first-release

• Добавим журнал изменений в индекс

  git add CHANGELOG.md
  git commit -am 'chore(site): add changelog'

• Зальём релизную ветку в основную ветку

  git flow release finish 1.0.0

• Отправим данные на github

  git push --all
  git push --tags

• Скопируем CHANGELOG.md в каталог release:

  mkdir -p ../release
  cp CHANGELOG.md ../release

• Создадим релиз на github. Для этого будем использовать утилиты работы с github (см. github: утилиты командной строки):

  gh release create v1.0.0 -F ../release/CHANGELOG.md

Видео