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

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

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

## Мультиязычность
Исходные файлы страниц доступны на нескольких языках в директории `/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
29
30
31
32
33
34
Любой, у кого есть аккаунт на GitLab, может создать отчёт (issue). Если ты
заметил какую-либо ошибку, даже если ты не знаешь, как её исправить,
[открой issue](https://gitlab.com/TulpaWiki/tulpawiki.gitlab.io/-/issues/new).
Не делай этого, если нашёл небольшую ошибку, например, опечатку, которую ты
при желании можешь исправить самостоятельно. В этом случае можешь исправить её
вместо того, чтобы писать об этом.
35
36
37
38
39
40
41
42
43
44
45

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

  Если ты заметил проблему на существующей странице, перейди [в подвал страницы](#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
46
47
48
49
По-умолчанию подразумевается, что у тебя есть аккаунт GitLab. Если по
каким-либо причинам ты не можешь использовать учётную запись GitLab, то для
автоматического создания отчёта можно отправить письмо на
[специальный адрес электронной почты](mailto:issue@tulpawiki.org).
50
51
52

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

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

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

### Поиск задач для работы
Maxim Lebedev's avatar
Maxim Lebedev committed
69
70
71
72
73
74
Если ты уже нашёл что исправить, то просто следуй инструкциям ниже. Для этого
тебе не обязательно [создавать 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
75
меткой `👋 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
76
77
78
79
быстрого поиска). Прочитай комментарии, чтобы убедиться, что для его решения
ещё не существует MR, а также, что никто другой не оставил комментарий, что он
работает над этой задачей в последнее время. Напиши комментарий, что ты бы
хотел заняться решением этой задачи.
80
81

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

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

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
99
100
101
Это только один из способов отправить MR. Если ты уже опытный пользователь Git
и GitLab, ты можешь вносить изменения, используя локальный GUI-клиент или Git
из терминала вместо того, чтобы использовать интерфейс GitLab для этого.
102
103

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

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

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