.. _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.12! 2. Запустите установочный файл и следуйте указаниям по установке. 3. Проверьте корректность установки: 1. Откройте терминал и выполните следующую команду: - Mac: ``python3 --version`` - Windows: ``python --version`` 2. Вы должны увидеть строку, похожую на следующую: ``Python 3.12.11`` .. note:: Если Вы не знаете, как открыть терминал, перейдите на шаг `Как открыть терминал`_. Установка системы контроля версий Git ------------------------------------- Чтобы установить систему контроля версий Git, выполните следующие шаги: 1. Скачайте установочный файл для своей системы с `официального сайта `__: .. image:: _static/starting_guide/git_main_page.png .. important:: Для скачивания нажмите кнопку ``Download for <название ОС>``. 2. Запустите установочный файл и следуйте указаниям по установке 3. Проверьте корректность установки: 1. Откройте терминал и выполните следующую команду: - ``git`` 2. Вы должны увидеть строку, похожую на следующую: ``usage: git ...`` .. note:: Если Вы не знаете, как открыть терминал, перейдите на шаг `Как открыть терминал`_. Установка среды разработки 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 .. important:: После данного шага **обязательно напишите добавленному ментору**, чтобы он мог принять запрос. 8. Проделайте шаги 4-7 для **всех менторов курса**. Точный список менторов уточняйте у преподавателей. Клонирование форка репозитория для локальной работы --------------------------------------------------- Чтобы склонировать форк на Вашу систему, выполните следующие шаги: 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:: Если Вы не знаете, как открыть терминал, перейдите на шаг `Как открыть терминал`_. Создание проекта в среде разработки 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 4. С помощью значка настроек |settingsIcon| в левом нижнем углу или сочетанием клавиш ``Ctrl + Shift + P`` откройте командную панель: .. image:: _static/starting_guide/vs_command_palette.png 5. Для создания виртуального окружения введите ``Python: Create Environment``, после выберите ``Venv``: .. image:: _static/starting_guide/vs_choose_venv.png 6. Введите путь к нужному интерпретатору. 7. Для активации виртуального окружения откройте терминал в среде разработки Visual Studio Code нажатием кнопки Terminal -> New Terminal в верхней панели или сочетанием клавиш ``Ctrl + ```: .. code-block:: bash python -m venv venv Вы готовы приступить к работе. .. note:: Для эффективной работы с Python следует установить расширение Python. Перейдите во вкладку Extensions в левой боковой панели (``Ctrl+Shift+X``). Введите id расширения в поисковую строку. Нужное нам - `ms-python.python` . Нажмите Install. .. 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: Изменение исходного кода ~~~~~~~~~~~~~~~~~~~~~~~~ По умолчанию функции не имеют внутри себя реализации - только ``pass`` в теле функции. Ваша задача - реализовать функцию по предоставленному описанию лабораторной работы. .. _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 3. В терминале выполните команду ``git commit -m "message"``: .. image:: _static/starting_guide/git_commit.png .. note:: В качестве ``message`` рекомендуется использовать краткое описание тех изменений, которые Вы сделали. Этот текст будет публично доступен! Больше информации о командах, описанных выше, можно найти в `официальной документации по Git `__. .. _pushing-changes: Отправка изменений в удалённый форк ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ После предыдущего шага изменения находятся в состоянии зафиксированных. Они сохранены только у Вас в системе. Чтобы отправить их в удалённый (находящийся на платформе GitHub) форк, созданный ранее, выполните следующие шаги: 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 pull``. 3. В терминале выполните команду ``git push``: .. image:: _static/starting_guide/git_push.png 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 `__ .. |settingsIcon| image:: _static/starting_guide/settingsIcon.svg