Внесение вклада в документацию Fedora
Добро пожаловать в команду документации Fedora. Если вы впервые участвуете в проекте с открытым исходным кодом, документация Fedora — отличное место для начала. Независимо от того, являетесь ли вы опытным участником или только начинаете, ваш вклад ценен и высоко ценится.
На этой странице будут описаны инструменты для работы с документацией, которые мы используем, и наш процесс рецензирования.
Цель документации
Зачем мы пишем документацию? По сути, чтобы помочь пользователям выполнять задачи. Если пользователь Fedora Linux может выполнить задачу быстрее, эффективнее или с большей легкостью, мы достигаем нашей цели. Хорошая документация имеет решающее значение для успеха проекта с открытым исходным кодом.
Какие навыки мне нужны?
Если у вас есть базовые знания Git и языка разметки AsciiDoc, вы готовы к работе. Если нет, уделите несколько минут чтению AsciiDoc для Fedora. AsciiDoc и Git легко освоить со временем.
Итак, вы готовы начать вносить вклад в документацию Fedora — что дальше?
Первые шаги
-
Создайте учётную запись Fedora Account System (FAS)
-
Присоединяйтесь к нашему каналу Matrix, чтобы поздороваться
-
Подпишите Соглашение участника проекта Fedora. Чтобы подписать соглашение, перейдите в свою учётную запись Fedora, выберите «Настройки», щёлкнув по изображению своего профиля в правом верхнем углу, а затем выберите вкладку «Соглашения». В качестве альтернативы, его можно найти здесь, подставив ваше фактическое имя пользователя: https://accounts.fedoraproject.org/user/your-username/settings/agreements/
-
Выберите задачу документации или предложите свою собственную и присоединяйтесь. Мы приветствуем все виды вклада, большие или маленькие.
Как работает документация
Репозитории
Документация Fedora состоит примерно из 60 git-репозиториев, часто с разными командами, ответственными за каждый репозиторий. Репозитории размещены на Fedora Forge, GitLab и GitHub. Ранее также было содержимое, размещенное на Pagure и вики Fedora. Многие репозитории теперь перенесены на Forge.
Как найти репозиторий
Чтобы найти исходный репозиторий страницы, нажмите кнопку редактирования: — расположенную в правом верхнем углу самой страницы документации.
Форки
Форк — это ваша собственная личная копия основного вышестоящего репозитория. Все редактирование выполняется внутри форка. Это позволяет вам вносить правки и экспериментировать с репозиторием без какого-либо влияния на основной вышестоящий репозиторий. По замыслу, большинство участников не имеют доступа для прямой фиксации изменений в основном вышестоящем репозитории.
Ветки
Ветка — это отдельная линия разработки внутри репозитория. Она служит точкой отсчета для конкретной области, над которой вы работаете, и означает, что правки в одной ветке не повлияют на другую. Большинство вышестоящих репозиториев имеют только одну ветку — ветку 'main'. Некоторые репозитории используют ветки для управления версиями, т.е. для документации, которая относится только к одной версии выпуска Fedora Linux.
Веб-сайт
Antora, генератор статических сайтов (SSG), извлекает исходное содержимое из репозиториев и генерирует веб-сайт документации Fedora, как показано на рисунке 2.
Antora используется потому, что она отлично справляется с компиляцией из нескольких исходных репозиториев для генерации единого сайта.
Исходные страницы
Текст документации пишется на языке разметки AsciiDoc. AsciiDoc используется, потому что это родной язык Antora SSG. Он тесно следует естественным стилям письма в повседневных заметках для структурирования и выделения. AsciiDoc можно писать практически в любом текстовом редакторе или текстовом процессоре.
О нашем процессе рецензирования
Документация Fedora следует политике четырех глаз, что означает, что второй человек (вторая пара глаз) должен проверить и одобрить изменение/добавление в документацию до того, как оно будет объединено с основным сайтом. Мы делаем это для поддержания точности и согласованности во всей нашей документации.
Открытие "запроса на включение" (PR) инициирует процесс рецензирования. Рецензенты проверяют грамматику, техническую точность, стиль и полноту. Это обычно приводит к объединению нового или исправленного текста с сайтом документации или к обсуждению улучшений.
Поток процесса рецензирования проиллюстрирован на рисунке 3.
Сроки рецензирования
Мы стремимся рассматривать и отвечать на PR в течение семи дней. Если вы не получили ответа в течение двух недель, пожалуйста, отправьте дружеское напоминание в нашем канале Matrix.
Подходы к редактированию
Существует два варианта редактирования: локально на вашем компьютере и непосредственно в веб-интерфейсе Forge. Оба подхода имеют разные сильные и слабые стороны. Вот сравнение:
Локально
Локальное редактирование позволяет вам:
-
Редактировать большие разделы или даже совершенно новые модули
-
Увидеть живую предварительную версию вашей работы точно так, как она будет выглядеть в конечном продукте.
-
Работать с несколькими файлами и репозиториями одновременно.
Хотя при локальном редактировании есть чему поучиться, мощь и гибкость, которые оно предоставляет, будут вознаграждены.
Обратитесь к руководству Локальный рабочий процесс для получения дополнительной информации.
Веб-интерфейс Forge
Правки можно вносить непосредственно в веб-интерфейсе Forge. Они лучше всего подходят для:
-
обновления небольших разделов
-
добавления или изменения ссылок
-
исправления опечаток и грамматики
Этот подход означает, что вам не нужно устанавливать какие-либо новые инструменты на свой компьютер. Он также не требует использования терминала. Однако у него есть некоторые ограничения при внесении более крупных изменений. Он не позволяет получить настоящую тестовую предварительную версию страниц. Изображения и перекрестные ссылки компилируются неправильно.
Обратитесь к руководству Редактирование одной страницы в Forge для получения дополнительной информации.
Типы вклада
Некоторые примеры вклада включают:
-
исправления мелких ошибок
-
добавления, удаления и изменения ссылок
-
пересмотра существующих страниц
-
написания новых страниц
-
перевода
-
общих идей по улучшению документации
Крупные вклады
Чем меньше PR, тем проще и быстрее его рецензировать. Если вы хотите выполнить крупный пересмотр страницы или написать совершенно новую страницу или раздел, свяжитесь с нами в канале Matrix документации Fedora. Это поможет гарантировать, что ваше время потрачено с умом, и позволит другим высказать свое мнение о направлении, которое мы выбираем вместе как проект.
Want to help? Learn how to contribute to Fedora Docs ›