.. _starting-guide-ru-label: Подготовка к прохождению курса ============================== Перед началом прохождения курса “Программирование для лингвистов” каждому студенту необходимо сделать несколько шагов, которые подготовят необходимые инструменты к дальнейшей работе. .. contents:: Содержание: :depth: 2 Установка интерпретатора языка программирования Python ------------------------------------------------------ Чтобы установить интерпретатор языка программирования Python на свой компьютер, выполните следующие шаги: 1. Скачайте установочный файл для своей системы с `официального сайта `__. .. image:: _static/starting_guide/download_python.png .. important:: Для скачивания нажмите кнопку ``Download Python 3.XX.XX``. Версия Python должна быть = 3.11! 2. Запустите установочный файл и следуйте указаниям по установке. 3. Проверьте корректность установки: 1. Откройте терминал и выполните следующую команду: - Mac: ``python3 -V`` - Windows: ``python -V`` 2. Вы должны увидеть строку, похожую на следующую: ``Python 3.11.2`` .. note:: Если Вы не знаете, как открыть терминал, перейдите на шаг `Как открыть терминал`_. Установка системы контроля версий Git ------------------------------------- Чтобы установить систему контроля версий Git, выполните следующие шаги: 1. Скачайте установочный файл для своей системы с `официального сайта `__: .. image:: _static/starting_guide/git_main_page.png .. important:: Для скачивания нажмите кнопку ``Download for <название ОС>``. 2. Запустите установочный файл и следуйте указаниям по установке 3. Проверьте корректность установки: 1. Откройте терминал и выполните следующую команду: - ``git`` 2. Вы должны увидеть строку, похожую на следующую: ``usage: git ...`` .. note:: Если Вы не знаете, как открыть терминал, перейдите на шаг `Как открыть терминал`_. Установка среды разработки PyCharm ---------------------------------- Чтобы установить среду разработки PyCharm, выполните следующие шаги: 1. Скачайте установочный файл для своей системы с `официального сайта `__: .. image:: _static/starting_guide/pycharm_download.png .. important:: Для скачивания нажмите кнопку ``Download``. .. note:: Рекомендуется использовать бесплатную версию Community Edition. Однако так как Вы являетесь студентом ВШЭ, то можете использовать и Professional Edition, зарегистрировавшись с учебной почты. Данная версия предоставляет `дополнительные возможности `__. 2. Запустите установочный файл и следуйте указаниям по установке. 3. Проверьте корректность установки: 1. Откройте PyCharm из меню приложений. 2. Вы должны увидеть похожий интерфейс: .. image:: _static/starting_guide/pycharm_project_selection.png Регистрация на платформе GitHub ------------------------------- Чтобы зарегистрироваться на платформе GitHub, выполните следующие шаги: 1. Откройте `главную страницу платформы `__. 2. В верхнем правом углу нажмите кнопку ``Sign up``: .. image:: _static/starting_guide/github_sign_up.png 3. Пройдите регистрацию. .. note:: Рекомендуется использовать личную почту, чтобы после окончания учёбы не пришлось менять почту с учебной на личную. .. note:: Рекомендуется (но не обязательно) в качестве логина использовать фамилию и имя. Пример: ``AndreiKashchikhin``. .. _creating-pat: Создание Personal Access Token для аутентификации ------------------------------------------------- Чтобы у Вас была возможность :ref:`взаимодействовать со своей рабочей машины с удалённым репозиторием `, Вам необходимо создать и использовать Personal Access Token (PAT). Чтобы создать PAT, выполните следующие шаги: 1. Откройте `главную страницу GitHub `__ и войдите в свой аккаунт. 2. В правом верхнем углу нажмите на свой аватар и из списка выберите ``Settings``: .. image:: _static/starting_guide/github_open_settings_from_main_page.png 3. Из списка слева выберите вкладку ``Developer settings``: .. image:: _static/starting_guide/github_developer_settings.png 4. Из списка слева выберите вкладку ``Personal access tokens``: .. image:: _static/starting_guide/github_pat_tab.png 5. Нажмите кнопку ``Generate new token``: .. image:: _static/starting_guide/github_generate_new_pat.png 6. Введите название для PAT в поле ``Note`` (1), выберите ``Expiration`` (2), поставьте галочку слева от настроек ``repo`` (3), ``workflow`` (4), ``gist`` (5): .. image:: _static/starting_guide/github_pat_settings.png 7. Внизу страницы нажмите кнопку ``Generate token``. 8. Нажмите кнопку копирования, чтобы перенести токен в буфер обмена: .. image:: _static/starting_guide/github_pat_copy.png .. important:: **Обязательно** сохраните этот токен! Он будет использоваться в других шагах в качестве пароля, необходимого для аутентификации. .. note:: После закрытия этой страницы, токен нельзя будет снова увидеть или найти на GitHub. 9. В следующих шагах инструкции при требовании пароля вводите сохранённый токен. Если у Вас возникают проблемы на каком-то из шагов, Вы можете обратиться к `официальной документации `__. Там же Вы можете узнать больше о PAT. Создание форка репозитория -------------------------- Чтобы создать форк репозитория на платформе 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 .. important:: После данного шага **обязательно напишите добавленному ментору**, чтобы он мог принять запрос. 8. Проделайте шаги 4-7 для **всех менторов курса**. - Список менторов Вы можете уточнить у преподавателей или найти в файле ``admins.txt``, который находится по пути ``<адрес-основного-репозитория>/config``. - `Пример для 2022 года `__. Клонирование форка репозитория для локальной работы --------------------------------------------------- Чтобы склонировать форк на Вашу систему, выполните следующие шаги: 1. Откройте сайт Вашего форка, который Вы создали на предыдущем шаге. 2. Нажмите кнопку ``Code``, выберите ``HTTPS`` и нажмите кнопку копирования: .. image:: _static/starting_guide/cloning_repository.png 3. Откройте терминал и перейдите в удобную папку: - Чтобы переходить из папки в папку в терминале, используйте команду ``cd <название-папки>``. - Пример: ``cd work``. 4. Выполните следующую команду для клонирования репозитория: - ``git clone <ссылка-на-ваш-форк>`` - Пример: ``git clone https://github.com/WhiteJaeger/2022-2-level-labs`` .. important:: Ссылку на форк Вы скопировали ранее на шаге №2. .. note:: При просьбе ввести пароль, введите :ref:`созданный Personal Access Token `. .. note:: Если Вы не знаете, как открыть терминал, перейдите на шаг `Как открыть терминал`_. Создание проекта в среде разработки PyCharm ------------------------------------------- Чтобы создать проект и работать с Вашим форком в среде разработки PyCharm, выполните следующие шаги: 1. Откройте PyCharm и нажмите кнопку ``Open``: .. image:: _static/starting_guide/opening_project.png 2. В открывшемся окне выберите папку с форком, который Вы склонировали на шаге `Клонирование форка репозитория для локальной работы`_: .. image:: _static/starting_guide/selecting_folder.png .. note:: На скриншоте выше показано, что форк был склонирован в папку ``PycharmProjects``. .. important:: Нужно выбрать именно **папку с форком**, имеющую название ``202X-2-level-labs``, а не папку с конкретной лабораторной работой. 3. В открывшемся окне нажмите кнопку ``OK``: .. image:: _static/starting_guide/setting_interpreter.png .. important:: Если в поле ``Base Interpreter`` версия Python < 3.9, то нажмите на ``Python 3.X`` и из выпадающего списка выберите более новую версию 4. Проект создан. Слева Вы можете увидеть файлы проекта: .. image:: _static/starting_guide/initial_project_setup.png .. _working-pipeline: Изменение исходного кода и отправка изменений в удалённый форк -------------------------------------------------------------- Основную работу Вы будете вести в файле ``main.py`` в папке с каждой лабораторной работой. Процесс выглядит следующим образом: 1. Вы изменяете исходный код в файле ``main.py``. 2. Вы фиксируете изменения с помощью системы контроля версий ``git``. 3. Вы отправляете изменения в удалённый форк. Далее будет пример этого процесса. .. _changing-code: Изменение исходного когда ~~~~~~~~~~~~~~~~~~~~~~~~~ По умолчанию функции не имеют внутри себя реализации - только ``pass`` в теле функции. Ваша задача - реализовать функцию по предоставленному описанию лабораторной работы. .. _committing-changes: Фиксация изменений с помощью системы контроля версий ``git`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Git - система контроля версий, которая позволяет сразу нескольким разработчикам сохранять и отслеживать изменения в файлах проекта. Сейчас мы зафиксируем изменения, сделанные на предыдущем шаге в файле ``main.py``. Чтобы это сделать, выполните следующие шаги: 1. Откройте терминал в среде разработки PyCharm: .. image:: _static/starting_guide/pycharm_open_terminal.png 2. В терминале выполните команду ``git add <путь-до-лабораторной-работы>/main.py``: .. image:: _static/starting_guide/git_add.png 3. В терминале выполните команду ``git commit -m "message"``: .. image:: _static/starting_guide/git_commit.png .. note:: В качестве ``message`` рекомендуется использовать краткое описание тех изменений, которые Вы сделали. Этот текст будет публично доступен! Больше информации о командах, описанных выше, можно найти в `официальной документации по Git `__. .. _pushing-changes: Отправка изменений в удалённый форк ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ После предыдущего шага изменения находятся в состоянии зафиксированных. Они сохранены только у Вас в системе. Чтобы отправить их в удалённый (находящийся на платформе GitHub) форк, созданный ранее, выполните следующие шаги: 1. Откройте терминал в среде разработки PyCharm: .. image:: _static/starting_guide/pycharm_open_terminal.png 2. В терминале выполните команду ``git pull``: .. note:: При просьбе ввести пароль, введите :ref:`созданный Personal Access Token `. 3. В терминале выполните команду ``git push``: .. image:: _static/starting_guide/git_push.png .. note:: При просьбе ввести пароль, введите :ref:`созданный Personal Access Token `. 4. Откройте главную страницу Вашего форка. Вы увидите сделанный *commit* и сообщение, которое Вы написали: .. image:: _static/starting_guide/fork_updated.png Больше информации о командах, описанных выше, можно найти в `официальной документации по Git `__. Создание 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 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 `__