23.6. Вклад в эту книгу

Вклад читателей помогает нам улучшать эту книгу. Если вы нашли опечатку, устаревшую ссылку, место, где, по вашему мнению, мы пропустили ссылку на источник, код, который выглядит неэлегантно, или объяснение, которое непонятно, пожалуйста, внесите свой вклад и помогите нам помочь нашим читателям. В обычных книгах задержка между печатными тирами (и, следовательно, между исправлениями опечаток) может составлять годы, тогда как в этой книге улучшение обычно внедряется за время от нескольких часов до нескольких дней. Всё это стало возможным благодаря контролю версий и непрерывной интеграции (CI) с тестированием. Для этого необходимо отправить pull request в репозиторий GitHub. Когда авторы примут ваш pull request в репозиторий с кодом, вы станете соавтором.

23.6.1. Внесение незначительных изменений

Наиболее распространёнными видами вклада являются редактирование одного предложения или исправление опечаток. Мы рекомендуем найти исходный файл в репозитории GitHub и отредактировать его напрямую. Например, вы можете воспользоваться кнопкой Find file (Fig. 23.6.1), чтобы найти исходный файл (файл формата markdown). Затем нажмите кнопку «Edit this file» в правом верхнем углу, чтобы внести изменения в файл markdown.

Fig. 23.6.1 Отредактируйте файл на GitHub.

После завершения работы заполните описание изменений в панели «Propose file change» внизу страницы, а затем нажмите кнопку «Propose file change». Вас перенаправит на новую страницу для проверки изменений (Fig. 23.6.7). Если всё в порядке, вы можете отправить запрос на слияние, нажав кнопку «Create pull request».

23.6.2. Предложение существенных изменений

Если вы планируете внести изменения в значительную часть текста или кода, вам следует узнать немного больше о формате, используемом в этой книге. Исходные файлы основаны на формате markdown с набором расширений, предоставляемых пакетом D2L-Book, таких как ссылки на уравнения, изображения, главы и цитаты. Вы можете использовать любой редактор markdown для открытия этих файлов и внесения изменений.

Если вы хотите внести изменения в код, мы рекомендуем использовать Jupyter Notebook для открытия этих markdown-файлов, как описано в Section 23.1, чтобы вы могли запускать и тестировать свои изменения. Пожалуйста, не забудьте очистить все выходные данные перед отправкой изменений, поскольку наша система CI выполнит обновленные разделы для генерации выходных данных.

Некоторые разделы могут поддерживать несколько реализаций на разных фреймворках. Если вы добавляете новый блок кода, используйте %%tab для маркировки этого блока в начале строки. Например, %%tab pytorch для блока кода PyTorch, %%tab tensorflow для блока кода TensorFlow или %%tab all для общего блока кода для всех реализаций. Дополнительную информацию можно найти в пакете d2lbook.

23.6.3. Внесение существенных изменений

Мы рекомендуем использовать стандартный процесс Git для внесения крупных изменений. Вкратце этот процесс описан в Fig. 23.6.2.

Fig. 23.6.2 Вклад в книгу.

Мы подробно рассмотрим все шаги. Если вы уже знакомы с Git, можете пропустить этот раздел. Для конкретности будем считать, что имя пользователя автора вклада — «astonzhang».

23.6.3.1. Установка Git

В книге Git с открытым исходным кодом описывается установка Git. Обычно это делается с помощью apt install git в Ubuntu Linux, установкой инструментов разработчика Xcode на macOS или использованием клиента GitHub для рабочего стола. Если у вас нет учётной записи GitHub, вам необходимо зарегистрироваться.

23.6.3.2. Вход в GitHub

Введите адрес репозитория с кодом книги в браузере. Нажмите кнопку Fork в красной рамке в правом верхнем углу Fig. 23.6.3, чтобы создать копию репозитория этой книги. Теперь это ваша копия, и вы можете изменять её как угодно.

Fig. 23.6.3 Страница репозитория кода.

Теперь репозиторий с кодом этой книги будет форкнут (то есть скопирован) в ваш аккаунт, как показано на рисунке Fig. 23.6.4 в верхнем левом углу, например, astonzhang/d2l-en.

Fig. 23.6.4 Форкнутый репозиторий с кодом.

23.6.3.3. Клонирование репозитория

Чтобы клонировать репозиторий (то есть создать его локальную копию), необходимо узнать его адрес. Он указан на зелёной кнопке в Fig. 23.6.5. Если вы планируете использовать эту форк-версию в долгосрочной перспективе, убедитесь, что ваша локальная копия синхронизирована с основным репозиторием. А пока просто следуйте инструкциям в Установка, чтобы начать. Главное отличие заключается в том, что теперь вы скачиваете свою собственную форк-версию репозитория.

Fig. 23.6.5 Клонирование репозитория.

# Replace your_github_username with your GitHub username
git clone https://github.com/your_github_username/d2l-en.git

23.6.3.4. Редактирование и отправка

Теперь пришло время отредактировать книгу. Лучше всего делать это в Jupyter Notebook, следуя инструкциям из Section 23.1. Внесите изменения и убедитесь, что они корректны. Предположим, что мы исправили опечатку в файле ~/d2l-en/chapter_appendix-tools-for-deep-learning/contributing.md. Затем вы можете проверить, какие файлы были изменены.

На этом этапе Git сообщит, что файл chapter_appendix-tools-for-deep-learning/contributing.md был изменен.

mylaptop:d2l-en me$ git status
On branch master
Your branch is up-to-date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   chapter_appendix-tools-for-deep-learning/contributing.md

Убедившись, что это именно то, что вы хотите, выполните следующую команду:

git add chapter_appendix-tools-for-deep-learning/contributing.md
git commit -m 'Fix a typo in git documentation'
git push

Изменённый код окажется в вашем личном форке репозитория. Чтобы предложить внести ваши изменения, необходимо создать pull request в официальный репозиторий книги.

23.6.3.5. Отправка pull-запросов

Как показано на рисунке Fig. 23.6.6, перейдите к своей форку репозитория на GitHub и выберите «New pull request». Откроется экран, на котором будут показаны изменения между вашими правками и текущим состоянием основного репозитория книги.

Fig. 23.6.6 Новый pull request.

Наконец, отправьте запрос на слияние, нажав на кнопку, как показано на рисунке Fig. 23.6.7. Обязательно опишите внесённые изменения в тексте запроса на слияние. Это облегчит авторам проверку и слияние изменений с книгой. В зависимости от характера изменений ваш запрос могут принять сразу, отклонить или, что более вероятно, вы получите обратную связь по внесённым изменениям. После их учёта ваш запрос будет готов к слиянию.

Fig. 23.6.7 Создайте запрос на слияние.

23.6.4. Итоги

• Вы можете внести свой вклад в эту книгу через GitHub.

• Вы можете редактировать файл на GitHub напрямую, чтобы внести незначительные изменения.

• Для внесения существенных изменений создайте форк репозитория, отредактируйте файлы локально и отправляйте изменения только после того, как будете готовы.

• Pull requests — это механизм объединения изменений. Старайтесь не создавать огромные pull requests, так как их сложно понять и интегрировать. Лучше отправлять несколько небольших.

23.6.5. Упражнения

1. Поставьте звезду и сделайте форк репозитория d2l-ai/d2l-en.

2. Если вы обнаружите неточности (например, отсутствие ссылки), отправьте pull request.

3. Обычно лучше создавать pull request из новой ветки. О том, как это сделать, читайте в разделе Git branching.

Обсуждения