beginner.ru.md 15.1 KB
Newer Older
1 2 3 4
---
title: Участие для начинающих
description: Инструкции и руководства для желающих внести вклад без опыта.
---
Maxim Lebedev's avatar
Maxim Lebedev committed
5 6
Если ты хочешь поучаствовать в работе над проектом, эта страница и связанные с
ней темы могут помочь тебе начать работу. Тебе не нужно быть разработчиком или
Maxim Lebedev's avatar
Maxim Lebedev committed
7
писателем, чтобы внести вклад в контент или улучшить сайт! Всё, что тебе
8
нужно - это учётная запись GitLab и браузер или любой провайдер почты.
9 10

## Основные сведенья
Maxim Lebedev's avatar
Maxim Lebedev committed
11 12 13
Весь контент написан на Markdown, обработан и развёрнут при помощи Hugo.
Исходные файлы находятся на GitLab по адресу [https://gitlab.com/TulpaWiki/tulpawiki.gitlab.io](https://gitlab.com/TulpaWiki/tulpawiki.gitlab.io).
Контент страниц хранится в директории `/content/`.
14

Maxim Lebedev's avatar
Maxim Lebedev committed
15 16 17
Ты можешь создавать новые задачи, редактировать содержимое и проверять
изменения от других участников, - всё это доступно с сайта GitLab. Ты также
можешь использовать встроенный в GitLab поиск и историю коммитов.
18 19 20 21 22 23 24 25 26

## Мультиязычность
Исходные файлы страниц доступны на нескольких языках в директории `/content/`.
Каждый язык имеет свой собственный двухбуквенный суффикс, определённым
стандартом [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php).
Например, страница `hello-world.md` для английского языка будет иметь имя
`hello-world.en.md`, а для русского - `hello-world.ru.md`.

## Создание хороших отчётов
Maxim Lebedev's avatar
Maxim Lebedev committed
27 28 29 30 31 32
Любой, у кого есть аккаунт на GitLab, может создать отчёт (issue). Если ты
заметил какую-либо ошибку, даже если ты не знаешь, как её исправить,
[открой issue](https://gitlab.com/TulpaWiki/tulpawiki.gitlab.io/-/issues/new).
Не делай этого, если нашёл небольшую ошибку, например, опечатку, которую ты
при желании можешь исправить самостоятельно. В этом случае можешь исправить её
вместо того, чтобы писать об этом.
33 34 35 36 37 38 39 40 41 42 43

### Как создать отчёт
* **Для существующей страницы**

  Если ты заметил проблему на существующей странице, перейди [в подвал страницы](#footer) и нажми ссылку "Сообщить об ошибке". Если ты ещё не авторизован на GitLab, сделай это. После этого откроется страница с формой для создания нового запроса в GitLab, где ты можешь выбрать шаблон.

  Подробно опиши свой запрос. Если у тебя есть предполагаемое решение проблемы, опиши его.
* **Запросить новую страницу**

  Если ты хочешь добавить что-то новое, но не уверен, как это сделать или считаешь, что новая информация не вписывается в существующие, всё равно создай issue. Ты можешь либо перейти на страницу, куда, по твоему мнению, нужно добавить новую информацию и создать отчёт прямо с этой страницы, либо перейти по ссылке [https://gitlab.com/TulpaWiki/tulpawiki.gitlab.io/issues/new](https://gitlab.com/TulpaWiki/tulpawiki.gitlab.io/issues/new) и написать чего ты хочешь там.

Maxim Lebedev's avatar
Maxim Lebedev committed
44 45 46 47
По-умолчанию подразумевается, что у тебя есть аккаунт GitLab. Если по
каким-либо причинам ты не можешь использовать учётную запись GitLab, то для
автоматического создания отчёта можно отправить письмо на
[специальный адрес электронной почты](mailto:[email protected]).
48 49 50

## Как заполнить хороший отчёт
Чтобы быть уверенным, что мы поймём тебя правильно:
Maxim Lebedev's avatar
Maxim Lebedev committed
51

52 53 54 55 56 57 58
* Используй шаблон issue и заполни его как можно подробнее;
* Чётко изложи суть твоей проблемы, как она сказывается на опыте других;
* Как можно меньше ограничь охват изменений в своём отчёте. Разбей большую задачу на более мелкие. Например, "Исправьте статью в архиве" не является проблемой, требующей немедленного решения, зато отчёт с заголовком "Исправьте ссылку на источник в статье 'Метод гимназистки'", вероятно, такой является.
* Если отчёт связан с другим, уже существующим отчётом или Merge Request, ты можешь сослаться на него, либо по полному URL, либо по его номеру с `#`. Например, `Зависит от #312`.
* Веди себя уважительно по отношению к другим и избегай жалоб. Например, заголовок "Гайд X отстой" явно не несёт ничего полезного чтобы на него реагировали.

## Улучшение существующего текста
Maxim Lebedev's avatar
Maxim Lebedev committed
59 60 61 62 63 64
Чтобы улучшить текущее содержимое, тебе нужно открыть Merge Request (MR) после
того, как ты сделаешь копию (fork) оригинального репозитория. Эти два термина
[относятся к GitLab](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html). Для начала работы, которая показана в этом
разделе, тебе не нужно знать всё про эти понятия, так как ты всё можешь
сделать через браузер. Когда ты перейдёшь к продвинутому руководству
участника, тогда тебе понадобится восполнить свои знания Git.
65 66

### Поиск задач для работы
Maxim Lebedev's avatar
Maxim Lebedev committed
67 68 69 70 71 72
Если ты уже нашёл что исправить, то просто следуй инструкциям ниже. Для этого
тебе не обязательно [создавать issue](#создание_хороших_отчётов) (хотя ты,
безусловно, можешь пойти этим путём).

Если ты ещё не определился с тем, над чем хочешь поработать, то перейди по
ссылке [https://gitlab.com/TulpaWiki/tulpawiki.gitlab.io/-/issues](https://gitlab.com/TulpaWiki/tulpawiki.gitlab.io/-/issues) и найди issue с
Maxim Lebedev's avatar
Maxim Lebedev committed
73
меткой `👋 help wanted` (ты можешь использовать [эту ссылку](https://gitlab.com/TulpaWiki/tulpawiki.gitlab.io/-/issues?label_name%5B%5D=%F0%9F%91%8B+help+wanted) для
Maxim Lebedev's avatar
Maxim Lebedev committed
74 75 76 77
быстрого поиска). Прочитай комментарии, чтобы убедиться, что для его решения
ещё не существует MR, а также, что никто другой не оставил комментарий, что он
работает над этой задачей в последнее время. Напиши комментарий, что ты бы
хотел заняться решением этой задачи.
78 79

### Выбор правильной ветки в Git
Maxim Lebedev's avatar
Maxim Lebedev committed
80 81 82
Самым важным моментом в создании запроса - это выбор нужной ветки для вашей
работы. Как правило, ветка `master` является лучшим выбором для исправления
ошибок или улучшения существующего текста.
83 84 85 86 87 88 89 90 91 92 93 94 95 96

### Создание запроса
Следуй описанным ниже шагам, чтобы создать запрос для улучшения проекта:

1. На странице, которую ты хочешь отредактировать, щёлкни по ссылке "Редактировать" [в подвале](#footer). Откроется новая страница на GitLab подсказкой. Нажми кнопку "Редактировать".
2. Если ты ранее не создавал копию репозитория, тебе будет предложено это сделать. Создай копию репозитория под своей учётной записью GitLab.
  Поскольку у тебя нет прав на изменение оригинального репозитория и соответственно ты не можешь отправлять напрямую свои изменения в `master` ветку, тебе нужно сделать копию репозитория.
3. Откроется редактор GitLab для редактирования исходного файла в формате Markdown. Внеси свои изменения. Под редактором заполни поле "Описание коммита", кратко описав чуть своих изменений в первой строке (до 120 символов) и (опционально) подробности через новую строку.
  **Примечание:** _Не ссылайся на другие issue или MR в сообщении коммита. Ты можешь сослаться на них в тексте MR._
4. Отобразится форма с заголовком New Merge Request. Название будет содержать краткое описание из сообщения коммита, хотя ты можешь изменить его при необходимости. В описании будет остальная информация из сообщения коммита (если оно есть) и небольшой шаблон с текстом. Прочитай текст шаблона и сделай то, что там описано, а затем удали этот шаблонный текст. Если ты добавишь в описание MR `fixes #<000000>` или `closes #<000000>`, где `#<000000>` - номер связанной issue, то GitLab автоматически закроет указанный отчёт при слиянии. Оставьте флажок "Разрешить коммиты от участников, которые могут выполнять слияние с целевой веткой" отмеченным. Нажми на кнопку "Submit запрос на слияние".
  **Примечание:** _Пожалуйста, открывай MR, изменения которого затрагивают только один язык. Например, если тебе нужно одинаково изменить один и тот же текст в нескольких языках, открой по отдельному MR для каждого языка._
5. Поздравляем! Твой MR добавлен в список. Ожидай, когда его проверят. Если куратор попросил изменить MR, ты можешь сделать это, если перейдёшь на вкладку со списком файлов и щёлкнешь на иконку с карандашом на любом изменённом файле. Сохрани новые изменения файла в виде нового коммита в ветке, указанной в MR. Если ты ожидаешь новую проверку изменений от рецензента, заранее попроси его об этом.
6. Если твои изменения одобрены, то куратор объединит твои изменения с основной кодовой базой. Через несколько минут ты сможешь увидеть их в действии на сайте.

Maxim Lebedev's avatar
Maxim Lebedev committed
97 98 99
Это только один из способов отправить MR. Если ты уже опытный пользователь Git
и GitLab, ты можешь вносить изменения, используя локальный GUI-клиент или Git
из терминала вместо того, чтобы использовать интерфейс GitLab для этого.
100 101

## Просмотр Merge Request
Maxim Lebedev's avatar
Maxim Lebedev committed
102 103 104 105 106 107 108 109 110 111
Новички могут обозревать MR. Ты можешь изучить кодовую базу и завоевать
доверие к себе со стороны других коллег-участников.

Обзоры не носят "обязательный характер", это означает, что только твоя
проверка не приведет к одобрению вносимых изменений. Тем не менее, это не
делает твои обзоры бесполезными. Даже только просмотр изменений в MR поможет
тебе понять как происходит рабочий процесс, какие могут быть трудности и
проблемы. Перед проверкой MR ознакомься с руководством по содержанию и
руководством по оформлению, чтобы узнать, каким должен быть содержимое и как
оно должно быть оформлено...
112 113 114 115 116 117 118 119

### Рекомендации
* Будь вежлив, внимателен и помогай другим;
* Также не забывай отмечать положительные стороны MR;
* Будьте чутким и думай, как твои комментарии могут быть восприняты другими;
* Прояви добрые намерения и задавай уточняющие вопросы;
* Опытным участникам: помогай новым участникам, их работа требует глаз да глаз;