Участие для начинающих

Если ты хочешь поучаствовать в работе над проектом, эта страница и связанные с ней темы могут помочь тебе начать работу. Тебе не нужно быть разработчиком или писателем, чтобы внести вклад в контент или улучшить сайт! Всё, что тебе нужно - это учётная запись GitHub и браузер или любой провайдер почты.

Основные сведенья

Весь контент написан на Markdown, обработан и развёрнут при помощи Hugo. Исходные файлы находятся на GitHub по адресу https://github.com/TulpaWiki/website. Контент страниц хранится в директории /content/.

Ты можешь создавать новые задачи, редактировать содержимое и проверять изменения от других участников, - всё это доступно с сайта GitHub. Ты также можешь использовать встроенный в GitHub поиск и историю коммитов.

Мультиязычность

Исходные файлы страниц доступны на нескольких языках в директории /content/. Каждый язык имеет свой собственный двухбуквенный суффикс, определённым стандартом ISO 639-1. Например, страница hello-world.md для английского языка будет иметь имя hello-world.en.md, а для русского - hello-world.ru.md.

Создание хороших отчётов

Любой, у кого есть аккаунт на GitHub, может создать отчёт (issue). Если ты заметил какую-либо ошибку, даже если ты не знаешь, как её исправить, открой issue. Не делай этого, если нашёл небольшую ошибку, например, опечатку, которую ты при желании можешь исправить самостоятельно. В этом случае можешь исправить её вместо того, чтобы писать об этом.

Как создать отчёт

Для существующей страницы
Если ты заметил проблему на существующей странице, перейди в подвал страницы и нажми ссылку “Сообщить об ошибке”. Если ты ещё не авторизован на GitHub, сделай это. После этого откроется страница с формой для создания нового запроса в GitHub, где ты можешь выбрать шаблон.
Подробно опиши свой запрос. Если у тебя есть предполагаемое решение проблемы, опиши его.
Запросить новую страницу
Если ты хочешь добавить что-то новое, но не уверен, как это сделать или считаешь, что новая информация не вписывается в существующие, всё равно создай issue. Ты можешь либо перейти на страницу, куда, по твоему мнению, нужно добавить новую информацию и создать отчёт прямо с этой страницы, либо перейти по ссылке https://github.com/TulpaWiki/website/issues/new и написать чего ты хочешь там.

По-умолчанию подразумевается, что у тебя есть аккаунт GitHub. Если по каким-либо причинам ты не можешь использовать учётную запись GitHub, то для автоматического создания отчёта можно отправить письмо на специальный адрес электронной почты.

Как заполнить хороший отчёт

Чтобы быть уверенным, что мы поймём тебя правильно:

Используй шаблон issue и заполни его как можно подробнее;
Чётко изложи суть твоей проблемы, как она сказывается на опыте других;
Как можно меньше ограничь охват изменений в своём отчёте. Разбей большую задачу на более мелкие. Например, “Исправьте статью в архиве” не является проблемой, требующей немедленного решения, зато отчёт с заголовком “Исправьте ссылку на источник в статье ‘Метод гимназистки’”, вероятно, такой является.
Если отчёт связан с другим, уже существующим отчётом или Merge Request, ты можешь сослаться на него, либо по полному URL, либо по его номеру с #. Например, Зависит от #312.
Веди себя уважительно по отношению к другим и избегай жалоб. Например, заголовок “Гайд X отстой” явно не несёт ничего полезного чтобы на него реагировали.

Улучшение существующего текста

Чтобы улучшить текущее содержимое, тебе нужно открыть Merge Request (MR) после того, как ты сделаешь копию (fork) оригинального репозитория. Эти два термина относятся к GitHub. Для начала работы, которая показана в этом разделе, тебе не нужно знать всё про эти понятия, так как ты всё можешь сделать через браузер. Когда ты перейдёшь к продвинутому руководству участника, тогда тебе понадобится восполнить свои знания Git.

Поиск задач для работы

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

Если ты ещё не определился с тем, над чем хочешь поработать, то перейди по ссылке https://github.com/TulpaWiki/website/-/issues и найди issue с меткой 👋 help wanted (ты можешь использовать эту ссылку для быстрого поиска). Прочитай комментарии, чтобы убедиться, что для его решения ещё не существует MR, а также, что никто другой не оставил комментарий, что он работает над этой задачей в последнее время. Напиши комментарий, что ты бы хотел заняться решением этой задачи.

Выбор правильной ветки в Git

Самым важным моментом в создании запроса - это выбор нужной ветки для вашей работы. Как правило, ветка master является лучшим выбором для исправления ошибок или улучшения существующего текста.

Создание запроса

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

На странице, которую ты хочешь отредактировать, щёлкни по ссылке “Редактировать” в подвале. Откроется новая страница на GitHub подсказкой. Нажми кнопку “Редактировать”.
Если ты ранее не создавал копию репозитория, тебе будет предложено это сделать. Создай копию репозитория под своей учётной записью GitHub. Поскольку у тебя нет прав на изменение оригинального репозитория и соответственно ты не можешь отправлять напрямую свои изменения в master ветку, тебе нужно сделать копию репозитория.
Откроется редактор GitHub для редактирования исходного файла в формате Markdown. Внеси свои изменения. Под редактором заполни поле “Описание коммита”, кратко описав чуть своих изменений в первой строке (до 120 символов) и (опционально) подробности через новую строку. Примечание: Не ссылайся на другие issue или MR в сообщении коммита. Ты можешь сослаться на них в тексте MR.
Отобразится форма с заголовком New Merge Request. Название будет содержать краткое описание из сообщения коммита, хотя ты можешь изменить его при необходимости. В описании будет остальная информация из сообщения коммита (если оно есть) и небольшой шаблон с текстом. Прочитай текст шаблона и сделай то, что там описано, а затем удали этот шаблонный текст. Если ты добавишь в описание MR fixes #<000000> или closes #<000000>, где #<000000> - номер связанной issue, то GitHub автоматически закроет указанный отчёт при слиянии. Оставьте флажок “Разрешить коммиты от участников, которые могут выполнять слияние с целевой веткой” отмеченным. Нажми на кнопку “Submit запрос на слияние”. Примечание: Пожалуйста, открывай MR, изменения которого затрагивают только один язык. Например, если тебе нужно одинаково изменить один и тот же текст в нескольких языках, открой по отдельному MR для каждого языка.
Поздравляем! Твой MR добавлен в список. Ожидай, когда его проверят. Если куратор попросил изменить MR, ты можешь сделать это, если перейдёшь на вкладку со списком файлов и щёлкнешь на иконку с карандашом на любом изменённом файле. Сохрани новые изменения файла в виде нового коммита в ветке, указанной в MR. Если ты ожидаешь новую проверку изменений от рецензента, заранее попроси его об этом.
Если твои изменения одобрены, то куратор объединит твои изменения с основной кодовой базой. Через несколько минут ты сможешь увидеть их в действии на сайте.

Это только один из способов отправить MR. Если ты уже опытный пользователь Git и GitHub, ты можешь вносить изменения, используя локальный GUI-клиент или Git из терминала вместо того, чтобы использовать интерфейс GitHub для этого.

Просмотр Merge Request

Новички могут обозревать MR. Ты можешь изучить кодовую базу и завоевать доверие к себе со стороны других коллег-участников.

Обзоры не носят “обязательный характер”, это означает, что только твоя проверка не приведет к одобрению вносимых изменений. Тем не менее, это не делает твои обзоры бесполезными. Даже только просмотр изменений в MR поможет тебе понять как происходит рабочий процесс, какие могут быть трудности и проблемы. Перед проверкой MR ознакомься с руководством по содержанию и руководством по оформлению, чтобы узнать, каким должен быть содержимое и как оно должно быть оформлено…