Назад к главной странице курса
Для всех лабораторных работ предусмотрена онлайн-сдача на сайте GitHub. Для этого нужно проделать ряд шагов, описанных ниже. Следует отметить, что данная инструкция не может претендовать не только на полноту описания возможностей Git, но даже на полноценное введение, поскольку не описывает и 10% его самых базовых функций. Для более глубокого понимания сути и принципов работы с Git обратитесь к ссылкам в конце данной инструкции.
Примечание: Ниже приведены консольные команды системы контроля версий Git. Существует также большое количество GUI-клиентов этой системы, их использование допускается, но не рекомендуется при отсутствии опыта работы с ними.
Схема работы с системой Git для сдачи лабораторных работ в графическом виде приведена на следующем рисунке.
Далее в этой инструкции детально описаны шаги, необходимые для выполнения и сдачи лабораторных работ. В процессе чтения инструкции можно возвращаться к вышеприведенному рисунку для более наглядного восприятия.
Необходимо создать аккаунт на сайте GitHub, если у вас его еще нет. Это можно сделать на главной странице https://github.com/ Бесплатный аккаунт позволяет создавать неограниченное количество репозиториев. Рекомендуется использовать реальный e-mail, поскольку через него будут осуществляться оповещения по ходу курса.
Для чего используется в реальной жизни: GitHub — крупнейший сервис для хостинга исходного кода и совместной разработки ПО, построенный на системе управления версиями Git.
Далее следует установить клиент системы управления версиями Git для вашей ОС. https://git-scm.com/downloads Он будет необходим для взаимодействия с сервером GitHub, а именно создания локальных репозиториев и отправки лабораторных работ на сервер. При установке в Windows необходимо выбрать опцию Use Git from the Windows Command Prompt, для того чтобы иметь возможность выполнять команды git из стандартного интерпретатора команд Windows cmd.exe.
Для чего используется в реальной жизни: Git — распределенная система управления исходными кодами программ. Используется для совместной работы с текстовой информацией. Позволяет хранить несколько версий документов и при необходимости переходить между ними. Также имеется возможность создания параллельных версий наборов документов с собственной хронологией, их объединение и множество других возможностей совместной разработки.
После установки требуется настроить клиент. Для этого из консоли требуется выполнить команды:
git config --global user.name "ваше_имя_пользователя"ваше_имя_пользователя — имя, которым будут подписаны ваши изменения. Рекомендуется выбрать такое имя, чтобы оно совпадало с вашим именем пользователя на GitHub.
git config --global user.email "ваш_email"ваш_email — адрес электронной почты, который указан в вашем профиле на GitHub.
Если есть желание потренироваться в использовании приемов работы с GitHub, можно использовать в качестве песочницы репозиторий db-course/students. В его описании указано, для чего он предназначен и как с помощью него можно отработать навыки перед сдачей лабораторных работ.
Необходимо форкнуть (fork) приватный репозиторий, относящийся к лабораторной работе, которую вы хотите сдать. Для этого необходимо зайти в репозиторий, соответствующий работе (например, icg-course/icg_labwork1 для 1-й ЛР), и нажать кнопку Fork.
Через несколько секунд на сервере GitHub будет создана ваша копия репозитория проекта.
Вы будете работать с ней, внося изменения в виде кода лабораторной работы, а затем для сдачи работы делать pull-request (запрос на включение) в исходный репозиторий, где его будет просматривать и оценивать преподаватель.
Для чего используется в реальной жизни: форк репозитория проекта — создание копии проекта на сервере. Это может преследовать разные цели:
-
Внесение собственного вклада в развитие чужого проекта. Для этого можно вносить соответствующие улучшения в свою копию проекта, а впоследствии путем использования pull-request (запроса на включение) предложить принять их в исходный проект его хозяину.
-
Создание собственного проекта на базе существующего.
После создания форка на сервере GitHub нужно клонировать его на свой собственный компьютер. Откройте интерпретатор команд (cmd.exe), перейдите к каталогу, в котором будете выполнять лабораторные работы (например d:\icg\lr), и выполните команду
git clone https://github.com/ваше_имя/имя_репозитория_с_лрНапример, если студент с именем пользователя ivanov собирается клонировать репозиторий с 1-й ЛР, для того чтобы сдать ее, необходимо выполнить команду
git clone https://github.com/ivanov/icg_labwork1Будет создан локальный каталог (в данном случае icg_labwork1), содержащий файл-шаблон лабораторной работы (имеет имя index.html), а также ряд других файлов, которые не относятся к работе и имеют служебное предназначение. Можно приступать к выполнению работы.
Изменения следует вносить в .html-файл, расположенный в локальном клоне вашего репозитория. Эта локальная копия также представляет собой репозиторий, который связан с исходным ссылкой origin (источник). Все изменения, которые вы вносите в файл, следует сначала сохранять в локальном репозитории, а затем направлять в репозиторий-источник (ваш форк, лежащий на сервере GitHub).
Вы изменили файл, сохранили его и хотите записать его состояние в локальный репозиторий. Для этого нужно сначала поместить его в индекс (stage) — промежуточный список файлов, который затем будет зафиксирован в качестве текущего состояния. Необходимо выполнить команду
git add имя_файлаЕсли вы хотите добавить в индекс несколько файлов, их имена в команде можно перечислить через пробел. Специальный синтаксис предусмотрен для добавления сразу всех измененных или добавленных файлов в индекс:
git add .Проверить состояние индекса можно командой
git statusЕсли изменения в файлы с момента предыдущей фиксации не вносились, статус будет пустым. Если есть неиндексированные изменения (были изменены отслеживаемые файлы, уже добавленные в индекс файлы или добавлены новые файлы), то соответствующие файлы будут отмечены красным цветом. После внесения командой add состояния файла в индекс соответствующий файл будет отображен зеленым цветом как готовый к фиксации.
Фиксация состояния файла (commit) выполняется командой
git commit -m "описание состояния"Здесь описание состояния — ваше сообщение, описывающее, что именно вы сохраняете. Например, так:
git commit -m "Добавлены новые узлы сложных геометрических объектов"После выполнения команды commit изменения зафиксированы в локальном репозитории.
Для чего используется в реальной жизни: commit (коммит) — снимок состояния проекта в конкретный момент времени, также может быть рассмотрен как список изменений, внесенный разработчиком в предыдущее состояние проекта. Цель системы контроля версий — обеспечение доступа пользователей к состоянию проекта в любой момент времени. Список коммитов представляет собой историю изменений конкретной ветки проекта. Можно получить к нему доступ командой git log. При публикации на сервер публикуются не только сами файлы, но и все их версии со связанными с ними изменениями. Например, список изменений репозитория с описанием этого курса можно посмотреть здесь: https://github.com/icg-course/syllabus/commits/master
Нет четкой рекомендации, сколько коммитов необходимо делать для одной лабораторной работы.
Можно наращивать изменения постепенно и документировать их, например:
git status
(нет изменений)...редактирование файлов...
git status
(есть неиндексированные изменения, выделены красным цветом)
git add измененные_файлы
git status
(все изменения индексированы, выделены зеленым цветом)...редактирование файлов...
git status
(есть неиндексированные изменения, выделены красным цветом)
git add измененные_файлы
git status
(все изменения индексированы, выделены зеленым цветом)
git commit -m "Добавлены геометрические примитивы"...редактирование файлов...
git status
(есть неиндексированные изменения, выделены красным цветом)
git add измененные_файлы
git status
(все изменения индексированы, выделены зеленым цветом)
git commit -m "Добавлены материалы"С другой стороны, можно отредактировать файл полностью, проиндексировать и закоммитить его. Это немного противоречит философии системы контроля версий, поскольку будет всего две версии вашего репозитория, начальная и исходная, без промежуточных, но допускается в учебных работах.
Если в лабораторной работе требуются дополнительные файлы (например, файл текстуры), которых не было в репозитории, то они добавляются путем копирования в рабочую директорию, добавления в индекс (git add имя_файла) и фиксации (git commit -m ...).
Для сдачи работы необходимо переписать (опубликовать) историю изменений (коммитов) из локального репозитория на сервер, в созданный вами репозиторий-форк. Напомним, на него указывает ссылка origin.
Для публикации истории служит команда push:
git push origin gh-pagesВ ней указывается, в какой репозиторий происходит публикация (origin — репозиторий-источник, который был клонирован) и какой ветви (gh-pages). В лабораторных работах используется ветвь gh-pages, что позволяет просматривать работы на хостинге Github Pages, не загружая их на локальный компьютер.
Для чего используется в реальной жизни: GitHub Pages — хостинг статических сайтов, предлагаемый сервисом GitHub, который позволяет бесплатно размещать сайты, храня их содержимое в репозитории на GitHub, и выделяет для них доменное имя (имя_репозитория.github.io). Один из способов воспользоваться хостингом - хранить страницы сайта в ветке репозитория gh-pages.
При публикации у вас могут быть затребованы учетные данные сайта GitHub, чтобы проверить, обладаете ли вы достаточными правами.
Публикация коммитов на сервер может быть не окончательной, вы можете продолжать работать над файлами, фиксировать изменения и публиковать их столько, сколько будет необходимо.
Чтобы сдать работу, необходимо отослать историю ваших изменений в центральный репозиторий этой работы в организации icg-course. Там их увидит и оценит преподаватель.
Выполнить push вы не сможете, т.к. не обладаете правами на запись в центральный репозиторий данной работы. Вместо этого вы можете отправить запрос на включение изменений (pull-request), и преподаватель получит уведомление о нем.
Для чего используется в реальной жизни: pull-request (запрос на включение) — основной способ вклада в проекты в открытым исходным кодом лицами, не являющимися членами проекта, но имеющими желание помочь. Помимо того, pull-request'ы могут использоваться внутри команды разработчиков проекта для обсуждения внесения изменений из одних ветвей проекта в другие.
Для создания pull-request'а зайдите на страницу своего репозитория и нажмите кнопку New pull request.
На появившейся странице будут отображены изменения, которые вы внесли в файлы репозитория. Нажмите Create pull request.
Далее вам будет предложено написать заголовок и комментарий к своему запросу. В заголовке напишите свою фамилию, инициалы, группу.
В комментарии к pull-request укажите ссылку на свою работу вида "https://ваше_имя.github.io/icg_labwork1", убедившись, что по данной ссылке можно просмотреть сцену.
Кнопка Create pull request внизу отправит ваш запрос на рассмотрение преподавателю.
Преподаватель сможет оставлять комментарии к вашему pull-request'у (например, для уточнения или указания на ошибки).
Вы можете также отвечать на комментарии.
При появлении новых событий, связанных со сдачей работы, в правом верхнем углу страницы сайта будет отображено уведомление.
Если вам необходимо доделать работу или исправить ошибки, то следует выполнить изменения в рабочем каталоге, зафиксировать их в локальном репозитории (подраздел "Выполнение лабораторной работы" данной инструкции) и опубликовать их в своем репозитории на GitHub (команда push). Эти изменения автоматически появятся в pull-request'е и будут доступны для рассмотрения преподавателем. После этого необходимо обязательно оставить в беседе комментарий, извещающий о сделанных вами изменениях, чтобы преподаватель увидел его.
В случае успешной сдачи преподаватель отмечает это соответствующим комментарием.
Для успешной сдачи лабораторной работы, необходимо, чтобы ее код прошел автоматическую валидацию в сервисе Travis CI. Она будет выполнена автоматически после добавления pull-request'а.
Для чего используется в реальной жизни: Travis CI - один из ряда сервисов, представляющих услуги "непрерывной интеграции" ("continuous integration, CI") для программных проектов. Идея непрерывной интеграции как методологии разработки ПО заключается в максимально частом проведении сборки, тестирования и развертывания проекта, в идеале - при внесении каждого изменения в него. Главное преимущество использование такого подхода - в раннем выявлении ошибок. Travis CI является отдельным сервисом, но имеет интеграцию с GitHub. В случае, если для репозитория на GitHub настроена непрерывная интеграция, после каждой операции push в репозиторий или в pull-request, код копируется в изолированный контейнер, запускаются заранее настроенные операции (сборка, тестирование и пр.) и формируется отчет о прохождении/непрохождении непрерывной интеграции.
Если проверка выявит ошибки в коде работы, об этом будет выведено уведомление. При этом по нажатию на "Details" можно увидеть, где в коде работы они были допущены.
После этого можно вносить исправления в код работы, они автоматически добавляются в pull-request и после каждого коммита с изменениями автоматическая валидация запускает повторно.
В случае успешного прохождения валидации никаких действий предпринимать не нужно, необходимо дождаться комментария от преподавателя.
Если вы сдали и защитили лабораторную работу и считаете, что она заслуживает оценки "отлично", а вы - соответствующей оценки при аттестации, вам необходимо опубликовать работу в каталоге работ. Принимайте во внимание, что ваша работа будет подписана вашим именем и фамилией и будет видна всем в интернете, в том числе другим поколениям студентов. Если у вас есть причины не размещать свою работу в публичном доступе, но при этом вам нужна оценка "отлично", необходимо согласовать эту ситуацию с преподавателем.
Если вам не нужна оценка "отлично", но вы считаете свои работы достойными и интересными, вы также можете опубликовать их в каталоге работ.
Для публикации работы (или работ) необходимо форкнуть репозиторий с каталогом работ (https://github.com/icg-course/icg-course.github.io) и клонировать его на локальный компьютер.
Важно! Если вы выкладываете работы не все сразу, либо если с момента клонирования прошло некоторое количество времени, за которое содержимое каталога работ на GitHub могло поменяться, необходимо обязательно выполнить в репозитории команду
git pullПосле этого вы будете иметь самую свежую локальную копию репозитория у себя, и изменения, которые вы произведете, не будут конфликтовать при попытке их публикации.
Далее вам надо зайти в папку репозитория и в папке со своим годом обучения создать папку со своим логином на GitHub. После этого необходимо в ней создать подпапку с названием - номером работы, которую вы размещаете в каталоге работ, и скопировать в нее все файлы работы (html-страницы, текстуры и т.д.). Копировать служебные файлы, которые были в репозитории работы до того, как вы ее выполнили (package.json, .travis.yml и прочие), нет необходимости, но если вы их скопировали - ничего страшного. Если вы хотите разместить сразу несколько работ - создавайте для каждой из них папку и копируйте туда работы.
Убедитесь, что главный файл называется index.html и расположен в корне папки с номером работы. Например, если ваш логин ivanov, и вы загружаете первую работу, главный файл должен быть расположен следующим образом: icg-course.github.io\2019\ivanov\1\index.html.
После этого будет необходимо отредактировать файл README.md в корне репозитория (icg-course.github.io\README.md), добавив туда свои фамилию и имя и ссылки на свои работы. Данный файл представляет собой текстовый файл в формате Markdown. С синтаксисом языка можно подробно ознакомиться здесь.
Для чего используется в реальной жизни: markdown - легкий язык разметки файлов, который был создан с целью получения максимально легко читаемого и редактируемого текстового файла, но имеющего разметку и способного быть сконвертированным в другие языки (например, HTML). Широко используется для создания текстового контента в интернете (например, эта инструкция также написана на Markdown).
В файле надо найти список студентов своего года обучения (если его нет - просто заголовок, соответствующий текущему году), после чего создать новый элемент ненумерованного списка со своими фамилией и именем, после которых в скобках разместить ссылки на свои работы.
Файл может иметь примерно такой вид:
## 2019
* Петров Петр ([1](https://icg-course.github.io/2019/petrov/1/), [2](https://icg-course.github.io/2019/petrov/2/))
После того, как пользователь ivanov, который также сдает работы в 2019 году, добавит ссылки на свои работы номер 1, 2 и 3, файл примет вид:
## 2019
* Петров Петр ([1](https://icg-course.github.io/2019/petrov/1/), [2](https://icg-course.github.io/2019/petrov/2/))
* Иванов Иван ([1](https://icg-course.github.io/2019/ivanov/1/), [2](https://icg-course.github.io/2019/ivanov/2/), [3](https://icg-course.github.io/2019/ivanov/3/))
Если вы уже добавляли прошлые работы в каталог, вам нужно найти в списке ваши фамилию и имя и дополнить список ссылок в скобках после них.
Если у вас есть несколько очень похожих работ (например, одна сделана на основе другой), не имеет смысла добавлять их все. Достаточно разместить самые удачные с вашей точки зрения работы, сделанные независимо друг от друга.
После добавления работ и изменения файла README.md можно зафиксировать изменения в репозитории. Поскольку данный репозиторий полностью отдан под сайт, хранимый на GitHub Pages, работа происходит в ветке master, а не gh-pages.
После этого необходимо выполнить
git pushи оформить pull-request в основном репозитории (icg-course/icg-course.github.io). Преподаватель обработает его, и если у него не возникнет замечаний, произведет слияние, после чего ваши работы и ссылки на них окажутся в каталоге https://icg-course.github.io/