Ревью от Оли

[yoursdearboy]

Предложения

Общие предложения

• Местами мне не хватает пунктуации (запятых) - я бы поправила, но ссылки "редактировать" не работают
• Раздел/ глава по организации совместной работы (роли, порядок действий) - см. далее комменты к «Главе 18»
• Раздел/ глава по конфликтам/ наиболее часто встречающимся ошибкам и что с ними делать

Глава 4 Настройка

• На мой взгляд, лучше перенести часть про имя и email после установки Git
• Можно сюда же добавить для тех, у кого Git уже установлен, как проверить, какое имя пользователя и какой email заданы

Глава 5 Создание репозитория

• Возможно, стоит добавить случай, когда папка уже есть, но в ней нет Rproj / когда уже есть Rproj, но нет Git репозитория
  • Я бы разделила прям на ситуации: если у вас еще нет папки для вашего рабочего проекта, в которой лежали бы данные/ ТЗ и т.п., если у вас уже есть папка на компьютере, но в ней нет файла .Rproj, если у вас уже есть папка с Rproj
  • Т.е. чтобы они различали папку на компьютере, проект R и гит-репозиторий. Может, тут какую-то схемку/ рисунок придумать: папка на компьютере - Rproj - репозиторий Git? что они могут существовать в разных сочетаниях друг с другом.
  • С этой точки зрения вопрос 3 может иметь несколько правильных вариантов ответа. + У меня, например, появляется еще файл .Rhistory
    • Или специально обозначить, что возможны такие-то ситуации, "из которых" вы создаете репозиторий Git, а дальше для этого курса создайте новую папку с проектом R и репозиторием Git - и вопрос про количество файлов в конце
• "Подробнее про рабочую папку":
  • Возможно, стоит добавить уточнение, что речь в примере с коллегой идет о папке с одним и тем же проектом
  • Также чуть детальнее расписать, к чему все это: например, что если необходимо поделиться проектом с коллегой и при этом в скриптах обращение к файлам будет осуществляться с помощью полного пути (пример), то у коллеги, которая положит этот проект на своем компьютере в место с другим адресом (пример), эта строчка скрипта не запустится и выдаст ошибку (текст ошибки). Та же проблема возникнет у вас, если вы перенесете свой проект в другую папку на своем компьютере и попытаетесь запустить этот скрипт.
  • Поэтому настоятельно рекомендуется при работе в R(Studio), независимо от того, будете ли вы пользоваться Git или нет, создавать проект (Rproj) и в скриптах вместо полных путей использовать относительные (пример). Это прям в рамочку поместить и привести на скриншоте пример, чтобы было понятно, что вот в такой-то папке мы создали проект - вот там лежит файлик Rproj - вот есть папка data, куда мы кладем файлы с данными - вот есть папка scripts, где у нас лежит скрипт .R, в котором мы загружаем файл такой-то из папки data таким-то образом, то есть пишем путь относительно рабочей папки.
    • По моему опыту, сколько раз это ни рассказывай (в том числе на курсе по знакомству в R), все равно будут те, кто пользуется полными путями...
  • И тогда, если вы поделитесь с другим пользователем папкой с проектом (и всем необходимым ее содержимым) или сами перенесете ее в другое место на своем компьютере, указанной выше ошибки в скрипте при запуске строки с загрузкой данных возникнуть не должно.
    • Можно дополнительно пояснить, что относительные пути актуальны и при сохранении каких-то промежуточных результатов (в виде файлов с таблицами или графиками) в процессе работы со скриптом (пример)
• На мой взгляд, да, нужно рассказать, что репозиторий - это папка с папкой .git. Дополнительно я бы еще показала, что эта папка появляется в папке с проектом, но ее не видно в RStudio (иначе по тексту складывается впечатление, что репозиторий - это папка, где лежит .gitignore)

Глава 6 Отслеживание изменений

• "Поэтому периодически необходимо фиксировать изменения в версии - " с помощью так называемых коммитов
• По поводу "коммит (версия)": мне казалось, что commit - это именно фиксация версии, то есть некоторое действие. Поэтому я бы их разделяла. Но если я не права (что вполне возможно), то ок
• "Для этого откройте папку в файловом менеджере или воспользуйтесь меню на панели Files в RStudio More → Show Folder in New Window" - не совсем поняла, зачем это (если файл будет скачиваться по ссылке, то его можно будет положить в папку проекта в процессе скачивания - или это на случай, если загрузка происходит в папку Загрузки, без выбора пути, чтобы потом его перенести в нужную папку? Если так, тогда, возможно, лучше переформулировать предложение в кавычках? Например, "Если что, папку с проектом можно открыть с помощью файлового менеджера в RStudio: для этого на панели Files в RStudio выберите меню :FabSettings2SvgrepoCom: More → Show Folder in New Window")

Глава 7 Рабочий процесс

• "Выполнив очередной шаг, мы отмечаем нужные изменения для фиксации (коммита), а ненужные убираем" - может возникнуть вопрос, что значит убираем и как убираем? потому что в примере до этого ненужных изменений не было
• Я бы объединила эту главу с предыдущей, взяв за название "Отслеживание изменений"
• Возможно, стоит здесь показать, как выглядит окошко commit, если мы меняем что-то в ранее сохраненной версии. Например, вначале мы сохранили penguins.R со строчкой, в которой считали данные. Потом добавили строчки для отрисовки и сохранения графика - это будет еще один коммит - показать, как будет выглядеть окошко commit, а потом, допустим, решили поменять ширину столбца и это следующий коммит - и вот тут рассказать про дифф и что означает раскраска строк в зеленый и красный цвет. Ну и сделать акцент, что вот на этом шаге уже мы сами себя контролируем, что поменялось по сравнению с последней версией. Так потом следующую главу будет проще понять, на мой взгляд (что потом мы все это в истории видим).
  • Иначе фраза "Отметьте его, проверьте изменения и создайте новый коммит." остается не совсем понятной (как проверить изменения?)

Глава 9 Введение (ветки)

• У меня ветка по умолчанию называется master, а не main (см. скриншот) - от чего это зависит? (у меня какая-то старая версия Git?) и на что в дальнейшем может повлиять?
  • Вдруг будут подобные мне динозавры
    ![[Pasted image 20250816194300.png]]
• На мой взгляд, главу лучше переименовать эту главу на что-то типа "Что такое ветка?" или объединить эту главу со следующей в "Создание ветки" (просто внутри раздела это выглядит несколько странно, особенно при наличии раздела Введение)

Глава 11 Переключение веток

• После примера в конце (с заменой содержимого скрипта penguins.R), возможно, лучше добавить, что не нужно (пере)запускать этот скрипт с сохранением новой гистограммы (для меня, например, это было неочевидно и я его запустила), чтобы потом, при слиянии веток, все выглядело так, как в примере

Глава 13 Заключение

• На мой взгляд, главу лучше переименовать в "Зачем нужны ветки" или "Когда использовать ветки"

Глава 14 Настройка

• "пароль от веб-сайта" - может, лучше "пароль от личного кабинета/ учетной записи GitHub"?

Глава 15 Удаленный репозиторий

• Скриншот с заполненной формой пусть останется
• "Далее скопируйте все три команды из раздела для существующего репозитория (… or push an existing repository from the command line, B) и выполните в терминале в RStudio"
• В "В чем разница между HTTPS и SSH?" пусто?

Глава 16 Загрузка изменений

• Для удобства можно выделить внутри этой главы 3 подраздела: загрузка из локального репозитория в удаленный через RStudio (push), изменения в удаленном репозитории через веб-интерфейс, загрузка удаленного репозитория на локальный компьютер (pull)
• "Сохраните и закомитьте файл penguins.R. После чего нажмите кнопку Push в верхнем правом углу." - я бы на скриншоте выделила порядок действий: 1 - commit, 2 - Push
• "Перейдите на страницу репозитория на GitHub и убедитесь, что коммит был загружен. Это можно понять по тексту сообщения над списком файлов и по тексту и времени изменения напротив файла penguins.R." - для наглядности можно выделить соответствующую строчку на скриншоте
• "Как и в случае с переключением веток, Git откажется загружать изменения и выдаст ошибку, если в рабочей папке имеются незафиксированные изменения, которые конфликтуют с загружаемыми" - лучше добавить к этому, что делать (вначале зафиксировать изменения в локальном репозитории (коммит) и только затем подгружать из удаленного (pull)? или это должно выглядеть как commit - push - pull?)

Глава 17 Pull request

• "GitHub предложит ввести заголовок и описание предлагаемых изменений. По правилам хорошего тона лучше кратко описать причину изменений и суть предлагаемого решения. А Также рекомендуется прокрутить страницу создания Pull Request и проверить изменения, которые вы предлагаете. После этого нажмите кнопку Create pull Request под полем с описанием."

Глава 18 Клонирование репозитория

• "Мы склонировали удаленный репозиторий на компьютер и теперь можем работать с ним как с оригинальным проектом — делать коммиты, загружать изменения в удаленный репозиторий (push) и из него (pull)." - тут мне не хватило вариантов развития событий:
  • если я хочу просто склонировать себе чей-то репозиторий, а затем работать с ним самостоятельно (допустим, преподаватель выложил что-то для задания, с которым каждый затем работает самостоятельно), то как это лучше сделать, чтобы не пушить в репозиторий по ссылке, а пушить в свой
  • для случая совместной работы над проектом (как будет у студентов в конце программы): что нужно, чтобы кто-то один создал удаленный репозиторий, остальные его клонируют, а затем... (перед своим пушем пулить или как?)
• Я бы вообще сделала отдельный раздел или хотя бы главу в разделе про GitHub про совместную работу над проектом: как она должна быть устроена (что нужно выбрать ответственного, за что он будет отвечать, каков порядок действий в этом случае - потому что именно здесь очень многое ломается, как показывает практика)

Глава 19 Заключение

• Может, это в отдельный раздел вынести, поскольку эта глава включает саммари по всем предыдущим главам, а не только по GitHub? Можно перенести отдельной главой в заключительный раздел, перед Best practices (только тогда переименовать его из Дополнительных материалов в Заключение)
• На схеме вместо Репозиторий лучше указать Локальный репозиторий?
• По схеме мне не очень понятны стрелки для переключения ветки и слияния ветки (почему они идут от репозитория к рабочей области - что это должно означать для пользователя)
• Где-то вначале было, но я бы тут еще раз добавила, что GitHub - это необязательная часть, если речь о самостоятельной работе над проектом

Глава 20 Best practices

• gitignore пустой? Тут предполагается написать, что лучше игнорить? Можно тогда с примерами, в том числе для игнора целых папок (не всем это очевидно)
• Принудительный push - нужно определение того, что это, когда может возникнуть такая необходимость, когда можно/ нельзя его делать + пример
  • Про git push --force должно быть тут, иначе в следующем пункте неочевидно, что эта команда и есть принудительный push
• Как перенести коммиты в ветку - для начала лучше описать, когда это может быть полезным.
  • В выделенном желтым с git push --force - лучше изложить по порядку или с примером. И этот абзац лучше перенести в конец
  • Лучше изложить прям по шагам 1/2/3, что делать, чтобы перенести коммиты в ветку (я, например, так и не поняла, где выделяются коммиты, которые я хочу выделить в отдельную ветку) - возможно, тут не хватает скриншотов

[yoursdearboy]

Глава 4 Настройка

На мой взгляд, лучше перенести часть про имя и email после установки Git

Ты имеешь в виду перенести в предыдущую главу «Установка» или оставить отдельной главой «Настройка», но не рассказывать перед этим про клиенты и терминал, а сразу перейти к настройке имени и email?

Моя мысль в том, что это короткая глава, где в любом случае придется поработать с терминалом. Поэтому это подходящее место, чтобы сказать о терминале и о других клиентах.

Возможно про клиенты стоит перенести в главу «Установка», но мне хотелось чтобы там была короткая
Тогда можно рассказать о клиентах отдельно, но нужно ли об этом говорить подробней, потому что работать мы будем с RStudio и терминалом.

[yoursdearboy]

Глава 5 Создание репозитория

...

Точно нужно рассмотреть создание репозитория для существующего проекта (добавил себе issue #8).
Наверное отдельной главой в доп. материалах, потому что сам курс хочется сделать линейным для прохождения, иначе кто-то точно запутается, что сейчас нужно делать.

Насчет создания проекта без репозитория — не уверен, потому что уже есть в курсе по автоматизации, а здесь используется для создания репозитория.
По этой же причине только коротко касаюсь полных и относительных путей, чтобы объяснить термин рабочая папка.
Возможно, в следующей версии отдельной (под)главой вынесу про проекты RStudio и там подробней расскажу про пути (issue #9).

чтобы они различали папку на компьютере, проект R и гит-репозиторий
На мой взгляд, да, нужно рассказать, что репозиторий - это папка с папкой .git. Дополнительно я бы еще показала, что эта папка появляется в папке с проектом, но ее не видно в RStudio (иначе по тексту складывается впечатление, что репозиторий - это папка, где лежит .gitignore)

Реально. Исправил, что репозиторий это папка .git, она скрытая и как ее посмотреть.
И в конце еще раз проговорил, что и то и другое это просто папки со служебными файлами и как они соотносятся.

[yoursdearboy]

Глава 6 Отслеживание изменений

"Поэтому периодически необходимо фиксировать изменения в версии - " с помощью так называемых коммитов
По поводу "коммит (версия)": мне казалось, что commit - это именно фиксация версии, то есть некоторое действие. Поэтому я бы их разделяла. Но если я не права (что вполне возможно), то ок

Используется и как глагол и как существительное, а коммит и версия используют взаимозаменяемо. На русском даже чаще говорят коммит. Например в «официальном» Pro Git.
В качестве действия везде стараюсь писать однородно «создать / выполнить / сделать коммит» (issue #11).

"Для этого откройте папку в файловом менеджере или воспользуйтесь меню на панели Files в RStudio More → Show Folder in New Window" - не совсем поняла, зачем это (если файл будет скачиваться по ссылке, то его можно будет положить в папку проекта в процессе скачивания - или это на случай, если загрузка происходит в папку Загрузки, без выбора пути, чтобы потом его перенести в нужную папку? Если так, тогда, возможно, лучше переформулировать предложение в кавычках? Например, "Если что, папку с проектом можно открыть с помощью файлового менеджера в RStudio: для этого на панели Files в RStudio выберите меню :FabSettings2SvgrepoCom: More → Show Folder in New Window")

Все так, потому что у меня сохраняется в загрузки) Поправил!

[yoursdearboy]

Глава 7 Рабочий процесс

"Выполнив очередной шаг, мы отмечаем нужные изменения для фиксации (коммита), а ненужные убираем" - может возникнуть вопрос, что значит убираем и как убираем? потому что в примере до этого ненужных изменений не было

Переписал вот так «Выполняем задачу и добавляем нужные для ее решения изменения в индекс, а лишние, например код для отладки или временные файлы, удаляем.»
Согласен, что надо ясней про "ненужные", но не хочу смещать фокус с процесса на подробности. Можно сделать пример с удалением ненужных изменений, например двух из 3-х гистограмм во втором шаге (issue #13).

Я бы объединила эту главу с предыдущей, взяв за название "Отслеживание изменений"

Предыдущая глава — это короткая инструкция как создать коммит, чтобы на нее можно было сослаться или они могли к ней вернуться. А цель этой главы 1) для практики создать несколько коммитов и 2) описать workflow «начали с чистой рабочей папки -> изменения -> индекс -> ревью -> коммит -> чистая рабочая папка -> повторить».

Может предыдущую назвать «Создание коммита» (неочевидное название, потому что понятие дается там), а эту «Отслеживание изменений»?

Возможно, стоит здесь показать, как выглядит окошко commit, если мы меняем что-то в ранее сохраненной версии. Например, вначале мы сохранили penguins.R со строчкой, в которой считали данные. Потом добавили строчки для отрисовки и сохранения графика - это будет еще один коммит - показать, как будет выглядеть окошко commit, а потом, допустим, решили поменять ширину столбца и это следующий коммит - и вот тут рассказать про дифф и что означает раскраска строк в зеленый и красный цвет. Ну и сделать акцент, что вот на этом шаге уже мы сами себя контролируем, что поменялось по сравнению с последней версией. Так потом следующую главу будет проще понять, на мой взгляд (что потом мы все это в истории видим).
Иначе фраза "Отметьте его, проверьте изменения и создайте новый коммит." остается не совсем понятной (как проверить изменения?)

Посмотри, пожалуйста, текущую версию — я значительно переработал эту главу и явно проговорил, когда делаются коммиты. Перенес сюда абзац про дифф и попросил его проверять.

[ejeej]

Внесла следующие правки из перечисленных (см. мой pull request):

• Глава 14
• Глава 15, п.2
• Глава 17

[ejeej]

Глава 4 Настройка

На мой взгляд, лучше перенести часть про имя и email после установки Git

Ты имеешь в виду перенести в предыдущую главу «Установка» или оставить отдельной главой «Настройка», но не рассказывать перед этим про клиенты и терминал, а сразу перейти к настройке имени и email?

Я еще раз прошлась по всему туториалу - эта часть пусть останется как есть (про имя пользователя и email).

[ejeej]

Глава 5 Создание репозитория

...

Да, всё ок! Про проект без репозитория не нужно, про репозиторий к существующему проекту ждем :)
Часть про пути и рабочую папку достаточно для базового курса.

[ejeej]

Глава 6 Отслеживание изменений

...

Принято 👍🏻

[ejeej]

Глава 7 Рабочий процесс

...

Да, всё ок с текущей версией.
И переименовывать в Основах вроде ничего не надо ))
Параллельный вопрос: про git restore где-то будет/ есть?