.. _starting-guide-label: Подготовка к прохождению курса ============================== Перед началом прохождения курса “Программирование для лингвистов” каждому студенту необходимо сделать несколько шагов, которые подготовят необходимые инструменты к дальнейшей работе. .. contents:: Содержание: :depth: 4 Установка интерпретатора языка программирования Python ------------------------------------------------------ Чтобы установить интерпретатор языка программирования Python на свой компьютер, выполните следующие шаги: 1. Скачайте установочный файл для своей системы с `официального сайта `__. .. image:: _static/starting_guide/download_python.png .. important:: Для скачивания нажмите кнопку ``Download Python 3.XX.XX``. Версия Python должна быть = 3.13! 2. Запустите установочный файл и следуйте указаниям по установке. 3. Проверьте корректность установки: 1. Откройте терминал и выполните следующую команду: - MacOS: ``python3 --version`` - Windows: ``python --version`` 2. Вы должны увидеть строку, похожую на следующую: ``Python 3.13.11`` .. note:: Если Вы не знаете, как открыть терминал, перейдите на шаг `Как открыть терминал`_. Если у Вас возникли ошибки при работе с терминалом, обратитесь к часто задаваемым вопросам по работе с терминалом (:ref:`terminal_faq`). Если после настройки у Вас остались вопросы, обратитесь в чат курса. Установка системы контроля версий Git ------------------------------------- Чтобы установить систему контроля версий Git, выполните следующие шаги: 1. Скачайте установочный файл для своей системы с `официального сайта `__: .. image:: _static/starting_guide/git_main_page.png .. important:: Для скачивания нажмите кнопку ``Download for <название ОС>``. 2. Запустите установочный файл и следуйте указаниям по установке 3. Проверьте корректность установки: 1. Откройте терминал и выполните следующую команду: - ``git`` 2. Вы должны увидеть строку, похожую на следующую: ``usage: git ...`` .. note:: Если Вы не знаете, как открыть терминал, перейдите на шаг `Как открыть терминал`_. Если у Вас возникли ошибки при работе с терминалом, обратитесь к часто задаваемым вопросам по работе с терминалом (:ref:`terminal_faq`). Если после настройки у Вас остались вопросы, обратитесь в чат курса. Установка среды разработки Visual Studio Code --------------------------------------------- Чтобы установить среду разработки Visual Studio Code, выполните следующие шаги: 1. Скачайте установочный файл для своей системы с `официального сайта `__: .. image:: _static/starting_guide/vscode_download.png 2. Запустите установочный файл и следуйте указаниям по установке. 3. Проверьте корректность установки: 1. Откройте Visual Studio Code из меню приложений. 2. Вы должны увидеть похожий интерфейс: .. image:: _static/starting_guide/vscode_project_selection.png Регистрация на платформе GitHub ------------------------------- Чтобы зарегистрироваться на платформе GitHub, выполните следующие шаги: 1. Откройте `главную страницу платформы `__. 2. В верхнем правом углу нажмите кнопку ``Sign up``: .. image:: _static/starting_guide/github_sign_up.png 3. Пройдите регистрацию. .. note:: Рекомендуется использовать личную почту, чтобы после окончания учёбы не пришлось менять почту с учебной на личную. .. note:: Рекомендуется (но не обязательно) в качестве логина использовать фамилию и имя. Пример: ``AndreiKashchikhin``. Создание форка репозитория -------------------------- Чтобы создать форк репозитория на платформе GitHub, выполните следующие шаги: 1. Откройте сайт репозитория, который Вам прислал преподаватель. 2. В верхнем правом углу нажмите кнопку ``Fork``: .. image:: _static/starting_guide/github_forking.png 3. На открывшейся странице нажмите кнопку ``Create Fork``: .. image:: _static/starting_guide/github_forking_2.png 4. Форк создан. Обратите внимание на ссылку в адресной строке браузера: она будет содержать **имя Вашего GitHub пользователя** и название репозитория: - ``https://github.com/<имя-Вашего-пользователя>/202X-2-level-labs`` .. image:: _static/starting_guide/github_forking_3.png Добавления менторов в коллабораторы ----------------------------------- В Ваш форк можете вносить изменения только Вы. В процессе прохождения курса может возникнуть ситуация, когда ментору будет необходимо внести изменения в Ваш форк (обновить Ваш форк до состояния основного репозитория, разрешить конфликты и т.д.). Чтобы у менторов была возможность вносить изменения в Ваш форк, их нужно добавить в *коллабораторы*. Для этого выполните следующие шаги: 1. Откройте сайт форка, который Вы создали на шаге `Создание форка репозитория`_. .. image:: _static/starting_guide/github_forking_3.png .. important:: Обратите внимание на ссылку в адресной строке браузера: она будет содержать **имя Вашего GitHub пользователя** и название репозитория. 2. Нажмите кнопку ``Settings``: .. image:: _static/starting_guide/github_settings.png 3. Слева выберите вкладку ``Collaborators``: .. image:: _static/starting_guide/github_collaborators_tab.png 4. Нажмите кнопку ``Add people``: .. image:: _static/starting_guide/github_add_collaborators.png 5. В открывшемся окне введите имя GitHub пользователя ментора и выберите его из списка: .. image:: _static/starting_guide/github_select_collaborator.png 6. Нажмите кнопку ``Add <имя-пользователя> to this repository``: .. image:: _static/starting_guide/github_add_collaborator_finish.png 7. Вы отправили запрос ментору на добавления в коллабораторы: .. image:: _static/starting_guide/github_add_collaborator_pending.png 8. Проделайте шаги 4-7 для **всех менторов курса**. Точный список менторов уточняйте у преподавателей. .. important:: **Обязательно напишите в чат**, если преподаватели не приняли Ваш запрос в течение нескольких дней. Клонирование форка репозитория для локальной работы --------------------------------------------------- Чтобы склонировать форк на Вашу систему, выполните следующие шаги: 1. Откройте сайт Вашего форка, который Вы создали на предыдущем шаге. 2. Нажмите кнопку ``Code``, выберите ``HTTPS`` и нажмите кнопку копирования: .. image:: _static/starting_guide/cloning_repository.png 3. Откройте терминал и перейдите в удобную папку: - Чтобы переходить из папки в папку в терминале, используйте команду ``cd <название-папки>``. - Пример: ``cd work``. 4. Выполните следующую команду для клонирования репозитория: - ``git clone <ссылка-на-ваш-форк>`` - Пример: ``git clone https://github.com/sofianurtdinova/2023-2-level-labs`` .. important:: Ссылку на форк Вы скопировали ранее на шаге №2. .. note:: Если Вы не знаете, как открыть терминал, перейдите на шаг `Как открыть терминал`_. Если у Вас возникли ошибки при работе с терминалом, обратитесь к часто задаваемым вопросам по работе с терминалом (:ref:`terminal_faq`). Если после настройки у Вас остались вопросы, обратитесь в чат курса. Создание проекта в среде разработки Visual Studio Code ------------------------------------------------------ Чтобы создать проект и работать с Вашим форком в среде разработки Visual Studio Code, выполните следующие шаги: 1. Откройте Visual Studio Code и нажмите кнопку ``Open``: .. image:: _static/starting_guide/vs_opening_project.png 2. В открывшемся окне выберите папку с форком, который Вы склонировали на шаге `Клонирование форка репозитория для локальной работы`_: .. image:: _static/starting_guide/vs_selecting_folder.png .. note:: На скриншоте выше показано, что форк был склонирован в папку ``Desktop (Рабочий стол)``. .. important:: Нужно выбрать именно **папку с форком**, имеющую название ``202X-2-level-labs``, а не папку с конкретной лабораторной работой. 3. В открывшемся окне нажмите кнопку ``Yes, I trust the authors``: .. image:: _static/starting_guide/vs_trust_authors.png 4. Проект создан, слева Вы можете увидеть файлы проекта: .. image:: _static/starting_guide/vs_initial_project_setup.png 5. Удостоверьтесь, что у Вас установлено расширение Python. Перейдите во вкладку Extensions в левой боковой панели (``Ctrl+Shift+X``). Введите id расширения в поисковую строку. Нужное нам — `ms-python.python`. Нажмите Install. 6. Для создания виртуального окружения откройте терминал (Terminal -> New Terminal в верхней панели или сочетание клавиш ``Ctrl + ```) и введите следующую команду: .. code-block:: bash python -m venv venv Это также можно сделать в командной панели. 1. Откройте командную панель с помощью значка настроек |settingsIcon| в левом нижнем углу или сочетанием клавиш ``Ctrl + Shift + P``: .. image:: _static/starting_guide/vs_command_palette.png 2. Введите ``Python: Create Environment``. 3. Выберите ``Venv``. 4. Выберите путь к нужному интерпретатору (обратите внимание, чтобы версия Python в выбранном интерпретаторе была подходящей для курса). Если интерпретатор Python не найден, обратитесь к инструкции по настройке переменных ``Path`` и ``PYTHONPATH`` :ref:`pythonpath_on_windows`, и затем попробуйте выбрать интерпретатор заново. 7. Выполните в терминале команду активации виртуального окружения. - Для macOS: ``.\venv\Scripts\activate`` - Для Windows: ``.\venv\Scripts\activate`` После успешной активации в начале строки появится метка (venv), а в правом левом углу при любом открытом `.py` файле появится значок с названием виртуального окружения и версией Python. При наведении мышки будет показан путь до интерпретатора. .. image:: _static/starting_guide/vscode_venv_bottom_right.png 8. Для корректной работы с пользовательскими модулями виртуальное окружение должно содержать нужные библиотеки. Текущие загруженные модули хранятся в ``venv/Lib/site-packages`` (Windows) или ``venv/lib//site-packages`` (macOS). В рамках курсов по програмированию все необходимые зависимости хранятся в файлах ``requirements.txt`` и ``requirements_qa.txt``. В дальнейшем если в лабораторной работе Вас попросят использовать внешнюю библиотеку, Вам следует добавить её в ``requirements.txt`` и установить зависимости заново. Установите зависимости с помощью команды: .. code-block:: bash python -m pip install -r requirements_qa.txt -r requirements.txt 9. Вы готовы приступить к работе. .. attention:: В Visual Studio Code изменения в файлах не сохраняются автоматически, но доступно автосохранение файлов. Чтобы его включить, выберите в левом верхнем углу File -> Auto Save. Для выбора режима необходимо настраивать автосохранение. Для этого нажмите сочетание клавиш ``Ctrl + ,`` или значок настроек в левом нижнем углу |settingsIcon| -> Settings -> в поисковой строке вбейте `Auto save`, после чего выберите один из доступных режимов. Подробнее о них можно почитать в `официальной документации Visual Studio Code `__ .. _working-pipeline: Изменение исходного кода и отправка изменений в удалённый форк -------------------------------------------------------------- Основную работу Вы будете вести в файле ``main.py`` в папке с каждой лабораторной работой. Процесс выглядит следующим образом: 1. Вы изменяете исходный код в файле ``main.py``. 2. Вы фиксируете изменения с помощью системы контроля версий ``git``. 3. Вы отправляете изменения в удалённый форк. Далее будет пример этого процесса. .. _changing-code: Изменение исходного кода ~~~~~~~~~~~~~~~~~~~~~~~~ По умолчанию функции не имеют внутри себя реализации. Ваша задача - реализовать функцию по предоставленному описанию лабораторной работы. .. _committing-changes: Фиксация изменений с помощью системы контроля версий ``git`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Git — система контроля версий, которая позволяет сразу нескольким разработчикам сохранять и отслеживать изменения в файлах проекта. Сейчас мы зафиксируем изменения, сделанные на предыдущем шаге в файле ``main.py``. Чтобы это сделать, выполните следующие шаги. Фиксация изменений через терминал """"""""""""""""""""""""""""""""" 1. Откройте терминал в среде разработки Visual Studio Code нажатием кнопки Terminal -> New Terminal в верхней панели или сочетанием клавиш ``Ctrl + ```: .. image:: _static/starting_guide/vs_open_terminal_0.png .. image:: _static/starting_guide/vs_open_terminal.png 2. В терминале выполните команду ``git add <путь-до-лабораторной-работы>/main.py``: .. image:: _static/starting_guide/git_add.png Если Вы хотите зафиксировать все изменённые файлы, замените путь до ``main.py`` на точку: ``git add .``. Однако будьте аккуратны с тем, какие файлы вы фиксируете. 3. В терминале выполните команду ``git commit -m "message"``: .. image:: _static/starting_guide/git_commit.png .. note:: В качестве ``message`` рекомендуется использовать краткое описание тех изменений, которые Вы сделали. Этот текст будет публично доступен! Больше информации о командах, описанных выше, можно найти в `официальной документации по Git `__. Альтернативный способ зафиксировать изменения """"""""""""""""""""""""""""""""""""""""""""" Можно также воспользоваться вкладкой ``Source Control`` Visual Studio Code. .. image:: _static/starting_guide/vs_source_control.png Здесь с помощью кнопки ``+`` Вы можете зафиксировать все нужные файлы. Они переместятся из вкладки ``Changes`` во вкладку ``Staged Changes`` (если после этого Вы добавили новые изменения в те же самые файлы, их также придётся добавить). Затем введите сообщение коммита и нажмите кнопку ``Commit`` .. image:: _static/starting_guide/vs_commit_staged.png .. _pushing-changes: Отправка изменений в удалённый форк ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ После предыдущего шага изменения находятся в состоянии зафиксированных. Они сохранены только у Вас в системе. Чтобы отправить их в удалённый (находящийся на платформе GitHub) форк, созданный ранее, выполните следующие шаги. Отправка изменений в удалённый форк через терминал """""""""""""""""""""""""""""""""""""""""""""""""" 1. Откройте терминал в среде разработки Visual Studio Code. 2. В терминале выполните команду ``git pull``. Это нужно делать каждый раз, когда преподаватели обновляют Ваш форк. 3. В терминале выполните команду ``git push``: .. image:: _static/starting_guide/git_push.png 4. Откройте главную страницу Вашего форка. Вы увидите сделанный *commit* и сообщение, которое Вы написали: .. image:: _static/starting_guide/fork_updated.png Больше информации о командах, описанных выше, можно найти в `официальной документации по Git `__. Альтернативный способ отправить изменения в удалённый форк """""""""""""""""""""""""""""""""""""""""""""""""""""""""" Альтернативный способ отправления изменений в удалённый форк — воспользоваться вкладкой ``Source Control`` Visual Studio Code. После сохранения коммита нажмите на кнопку ``Sync Changes (number of commits)``. Кнопка синхронизации покажет, сколько входящих коммитов (тех, что Вы принимаете с помощью ``git pull`` — стрелка вниз) и Ваших исходящих коммитов (стрелка вверх) будет синхронизировано. .. image:: _static/starting_guide/vs_push.png Вы можете сделать ``git pull`` через ``Source Control``, нажав соответствующую кнопку в блоке ``More Actions`` (три точки на строке блока ``Changes``). .. image:: _static/starting_guide/vscode_source_control_additional.png Во вкладке ``Graph`` все коммиты, сохранённые локально, будут отмечены названием ветки (`main` в данном случае), а все коммиты, отправленные в удалённый репозиторий, будут иметь вид `origin/<название-ветки>`. Конфликты """"""""" Если у Вас были входящие коммиты, у Вас могут образоваться конфликты. Если Вы не знаете, как решать конфликты, обратитесь в чат за помощью. Указание ``origin`` для ``git push`` """""""""""""""""""""""""""""""""""" Когда Вы делате ``git pull/push`` в первый раз, Вам может понадобиться настроить то, куда Вы отправляете изменения и откуда принимаете их. Убедитесь, что при запуске команды ``git remote -v`` Ваш вывод выглядит следующим образом: origin — Ваш форк, а upstream — основной репозиторий. .. image:: _static/starting_guide/git_remote.png Если что-то выглядит иначе, выполните команду добавления соответствующего репозитория: .. code:: bash git remote add upstream <ссылка-на-главный-репозиторий> git remote add origin <ссылка-на-Ваш-форк> Выполение ``git push`` через ``Source Control`` может также потребовать настройки того, куда Вы отправляете изменения. Кнопка ``Sync Changes`` будет выглядеть как ``Publish Branch``. Вам нужно будет указать origin — ссылку на Ваш форк. Авторизация на шаге ``git push`` """""""""""""""""""""""""""""""" Если для выполнения ``git push`` VSCode требует от Вас авторизироваться, в качестве имени и почты введите Ваше имя или ник на GitHub и почту, с помощью которой Вы регистрировались на GitHub. .. code:: bash git config --global user.name "Your Name" git config --global user.email your-e-mail@example.com Если у Вас запрашивают пароль, это не пароль от GitHub. Вам необходимо сгенерировать Personal Access Token на GitHub. 1. Для этого перейдите в настройки и внизу страницы в левом блоке найдите раздел ``Developer settings``. .. image:: _static/starting_guide/github_find_settings.png 2. Выберите тип токена для генерации (classic): .. image:: _static/starting_guide/github_pat_tab.png 3. Введите название для PAT в поле Note (1), выберите Expiration (2), поставьте галочку слева от настроек repo (3), workflow (4), gist (5): .. image:: _static/starting_guide/github_pat_settings.png 4. Внизу страницы нажмите кнопку ``Generate token``. 5. Нажмите кнопку копирования, чтобы перенести токен в буфер обмена: .. image:: _static/starting_guide/github_pat_copy.png .. important:: Обязательно сохраните этот токен! Его нельзя будет увидеть снова — только сгенерировать новый. 6. Вставьте сохранённый токен в поле, требующее пароля (``ctrl+V`` или кликом правой клавиши мыши). Создание Pull Request --------------------- Чтобы менторы смогли увидеть Ваши изменения и сделать проверку, Вам нужно создать Pull Request на платформе GitHub. Для этого выполните следующие шаги: 1. Откройте сайт репозитория, который Вам прислал преподаватель. 2. Выберите вкладку Pull Requests: .. image:: _static/starting_guide/github_pull_request_highlighted.png 3. Нажмите кнопку ``New pull request``: .. image:: _static/starting_guide/github_new_pull_request.png 4. Нажмите кнопку ``compare across forks``: .. image:: _static/starting_guide/github_compare_across_forks.png 5. Нажмите ``head repository`` и из списка выберите Ваш форк (он будет содержать имя Вашего пользователя): .. image:: _static/starting_guide/github_choose_fork.png 6. Нажмите кнопку ``Create pull request``: .. image:: _static/starting_guide/github_create_pull_request_final_step.png 7. Введите название для Pull Request: .. image:: _static/starting_guide/github_name_pull_request.png .. important:: Имя PR должно соответствовать следующему шаблону: ``Laboratory work #X, Name Surname - 2XFPLX``. 8. Нажмите ``Assignees`` и из списка выберите ментора, который указан в таблице успеваемости: .. image:: _static/starting_guide/github_assignees.png Учтите, что для выставления ``Assignees`` может понадобится дождаться, когда Вас добавят в команду курса. О сроках напишут преподаватели, а приглашение придёт на почту, с которой Вы регистрировались на GitHub. Если Вы ещё не приняли приглашение, создавайте форк без ``Assignees`` — это поле можно будет заполнить позже. 9. Нажмите кнопку ``Create pull request``: .. image:: _static/starting_guide/github_create_pull_request_done.png .. note:: Pull Request появится в списке PR, который находится на странице из шага №2. Продолжение работы ------------------ Продолжение работы заключается в повторении нескольких шагов: 1. :ref:`Вы изменяете исходный код `. 2. :ref:`Вы фиксируете изменения `. 3. :ref:`Вы отправляете изменения в удалённый форк `. - Они автоматически будут обновляться и в Pull Request, который Вы создали. 4. Ментор проверяет Ваш код и оставляет комментарии. 5. Вы исправляете исходный код согласно комментариям. 6. См. шаг №2. Как открыть терминал -------------------- 1. `Инструкция для Windows `__ 2. `Инструкция для MacOS `__ .. |settingsIcon| image:: _static/starting_guide/settingsIcon.svg