Руководство по внесению вклада 26.1.2

Руководство по внесению вклада в документацию Fabric

Этот сайт использует VitePress для генерации статического HTML-кода из различных Markdown-файлов. Вы можете ознакомиться с Markdown-расширениями для VitePress здесь.

Есть три пути для внесения своего вклада для сайта:

• Перевод документации
• Вклад в содержимое
• Руководство по внесению вклада

Все материалы должны соответствовать нашим рекомендациям по стилю.

Перевод документации

Если вы хотите перевести документацию на свой язык, вы можете сделать это на странице Fabric на Crowdin.

new-content Внесение контента

Основной способ внести вклад в документацию Fabric — это внесение контента.

Все материалы, добавляемые в контент, проходят следующие этапы, каждому из которых соответствует метка:

1. locally: Подготовьте изменения и отправьте pull request
2. stage:expansion: Рекомендации по расширению, если необходимо
3. stage:verification: Проверка содержимого
4. stage:cleanup: Грамматика, Линтинг...
5. stage:ready: Готово к релизу!

Всё содержимое должно соответствовать нашим рекомендациям по стилю.

1. Подготовьте свои изменения

Этот сайт с открытым исходным кодом, он разрабатывается в репозитории GitHub, что означает, что мы полагаемся на поток GitHub:

1. Создайте форк репозитория на GitHub
2. Создайте новую ветку в вашем форке
3. Сделайте свои изменения в этой ветке
4. Откройте запрос на изменение в оригинальном репозитории

Вы можете прочитать больше о потоке GitHub.

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

Клонирование вашего форка

Если вы хотите разрабатывать локально, вам нужно будет установить Git.

После этого клонируйте свой форк репозитория с помощью:

# make sure to replace "your-username" with your actual username
git clone https://github.com/your-username/fabric-docs.git

Установка зависимостей

Если вы хотите предварительно локально просматривать свои изменения, вам нужно будет установить Node.js версии 18 или выше и pnpm.

После этого убедитесь, что все зависимости установлены с помощью:

pnpm install

Запуск сервера разработки

Это позволит вам предварительно просматривать ваши изменения локально по адресу localhost:5173 и автоматически перезагрузит страницу при внесении изменений.

pnpm dev

Теперь вы можете открыть сайт и просматривать его из браузера, посетив http://localhost:5173.

Создание веб-сайта

Это скомпилирует все файлы с Markdown в статические HTML-файлы и поместит их в .vitepress/dist:

pnpm build

Предварительный просмотр созданного веб-сайта

Это запустит локальный сервер на порту 4173, отображающий содержимое, найденное в .vitepress/dist:

pnpm preview

Открытие запроса

Если вы довольны своими изменениями, вы можете push ваши изменения:

git add .
git commit -m "Description of your changes"
git push

Затем, зайдите по ссылке в выводе команды git push, чтобы открыть PR.

2. stage:expansion Рекомендации по расширению, если необходимо

Если команда по документированию считает, что вы могли бы расширить свой запрос, один из членов команды добавит метку stage:expansion к вашему запросу с комментарием, объясняющим, что, по их мнению, вы могли бы расширить. Если вы согласны с этим предложением, вы можете дополнить свой реквест.

Если вы не хотите дополнять свой реквест, но будете рады, что кто-то другой дополнит его позже, лучше всего создать пост на странице проблем и объяснить, что, по вашему мнению, можно было бы дополнить. Затем группа по документированию добавит метку требуется помощь к вашему PR.

3. stage:verification Проверка содержимого

Это самый важный этап, поскольку он гарантирует точность контента и его соответствие руководству по стилю Fabric Documentation.

На этом этапе необходимо ответить на следующие вопросы:

• Все ли содержания верно?
• Весь ли контент актуален?
• Охватывает ли контент все случаи, например, различные операционные системы?

4. stage:cleanup: Очистка

На этом этапе происходит следующее:

• Исправление любых грамматических ошибок с помощью LanguageTool
• Анализ всех файлов Markdown с помощью markdownlint
• Форматирование всего кода Java с использованием Checkstyle
• Другие различные исправления и улучшения

framework Вносящий вклад в фреймворк

Фреймворк относится к внутренней структуре веб-сайта. Любые запросы, которые изменяют фреймворк веб-сайта, будут помечены меткой framework.

К вашему сведению, вы должны делать pull requests, касающиеся фреймворка, только после консультации с командой документации на Discord-сервере Fabric или через issue.

INFO

Изменение файлов боковой панели и конфигурации панели навигации не считается pull request, касающимся фреймворка.

Стандарты оформления

Если вы насчёт чего-то не уверены, можете задать свой вопрос в Fabric Discord или через GitHub Discussions.

Пишите оригинал на американском английском

Вся оригинальная документация написана на английском языке в соответствии с американскими правилами грамматики.

Добавляйте данные в начало файла

Все страницы должны иметь заголовок и описание.

Не забывайте также добавлять ваше имя пользователя GitHub в поле authors в начале Markdown-файла! Таким образом, мы сможем отдать вам должное.

---
title: Title of the Page
description: This is the description of the page.
authors:
  - your-username
---

Добавляйте "якоря" к заголовкам

Каждый заголовок должен иметь "якорь", который используется для создания ссылки на этот заголовок:

## This Is a Heading {#this-is-a-heading}

Якорь должен состоять из строчных букв, цифр и дефисов.

Размещайте код внутри Example мода

Если вы создаете или изменяете страницы, содержащие код, размещайте этот код в соответствующем месте внутри Example мода (он находится в папке /reference репозитория). Затем используйте функцию импорта фрагментов/кусков кода, которую предоставляет VitePress, чтобы встроить этот код на страницу.

Например, чтобы подсветить строки с 15 по 21 в файле ExampleMod.java из этого мода:

md

<<< @/reference/latest/src/main/java/com/example/docs/ExampleMod.java{15-21}

java

package com.example.docs;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import net.minecraft.core.Registry;
import net.minecraft.core.component.DataComponents;
import net.minecraft.core.particles.SimpleParticleType;
import net.minecraft.core.registries.BuiltInRegistries;
import net.minecraft.resources.Identifier;
import net.minecraft.tags.BiomeTags;
import net.minecraft.world.level.levelgen.GenerationStep;

import net.fabricmc.api.ModInitializer;
import net.fabricmc.fabric.api.biome.v1.BiomeModifications;
import net.fabricmc.fabric.api.biome.v1.BiomeSelectors;
import net.fabricmc.fabric.api.item.v1.ItemComponentTooltipProviderRegistry;
import net.fabricmc.fabric.api.particle.v1.FabricParticleTypes;

import com.example.docs.component.ModComponents;
import com.example.docs.worldgen.ExampleModWorldPlacedFeatures;

public class ExampleMod implements ModInitializer {
	// This logger is used to write text to the console and the log file.
	// It is considered best practice to use your mod id as the logger's name.
	// That way, it's clear which mod wrote info, warnings, and errors.
	public static final String MOD_ID = "example-mod";
	public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);

	// This DefaultParticleType gets called when you want to use your particle in code.
	public static final SimpleParticleType SPARKLE_PARTICLE = FabricParticleTypes.simple();

	@Override
	public void onInitialize() {
		// This code runs as soon as Minecraft is in a mod-load-ready state.
		// However, some things (like resources) may still be uninitialized.
		// Proceed with mild caution.

		LOGGER.info("Hello Fabric world!");

		// Register our custom particle type in the mod initializer.
		Registry.register(BuiltInRegistries.PARTICLE_TYPE, Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "sparkle_particle"), SPARKLE_PARTICLE);
		// Spawns everywhere in the overworld
		BiomeModifications.addFeature(
				BiomeSelectors.foundInOverworld(),
				GenerationStep.Decoration.UNDERGROUND_ORES,
				ExampleModWorldPlacedFeatures.DIAMOND_BLOCK_ORE_PLACED_KEY
		);

		// Spawns in forest biomes only
		BiomeModifications.addFeature(
				BiomeSelectors.tag(BiomeTags.IS_FOREST),
				GenerationStep.Decoration.VEGETAL_DECORATION,
				ExampleModWorldPlacedFeatures.DIAMOND_TREE_PLACED_KEY
		);

		ItemComponentTooltipProviderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.COMPONENT_WITH_TOOLTIP);
		ItemComponentTooltipProviderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.ADVANCED_CUSTOM_COMPONENT);
	}
}

Если вам нужен более широкий диапазон контроля, вы можете использовать функцию transclude из markdown-it-vuepress-code-snippet-enhanced.

Например, это встроит секции файла выше, которые помечены тегом #entrypoint:

md

<<< @/reference/latest/src/main/java/com/example/docs/ExampleMod.java#entrypoint

ExampleMod.java

public class ExampleMod implements ModInitializer {
	// This logger is used to write text to the console and the log file.
	// It is considered best practice to use your mod id as the logger's name.
	// That way, it's clear which mod wrote info, warnings, and errors.
	public static final String MOD_ID = "example-mod";
	public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);

	@Override
	public void onInitialize() {
		// This code runs as soon as Minecraft is in a mod-load-ready state.
		// However, some things (like resources) may still be uninitialized.
		// Proceed with mild caution.

		LOGGER.info("Hello Fabric world!");
	}
}

Создавайте боковую панель для каждого нового раздела

Если вы создаете новый раздел, вам следует создать новую боковую панель в папке .vitepress/sidebars и добавить её в файл i18n.mts.

Если вам нужна помощь с этим, спросите в дискорде Fabric в канале #docs.

Добавьте новые страницы в соответствующие боковые панели

При создании новой страницы вы должны добавить ее на соответствующую боковую панель в папке .vitepress/sidebars.

Опять же, если вам нужна помощь, спросите в дискорде Fabric в канале #docs.

Используйте /assets для хранения медиаконтента

Любые изображения должны находиться в соответствующем месте в папке /assets.

Используйте относительные ссылки!

Это требуется для правильной работы системы с разными версиями, которая заранее обрабатывает ссылки для добавления версии. Если вы используете обычные ссылки, номер версии не будет добавлен к ссылке.

Также, вы не должны добавлять расширение файла к ссылке.

Например, чтобы сослаться на страницу /players/index.md со страницы /develop/index.md, вам нужно сделать следующее:

✅ Correct

This is a relative link!
[Page](../players/index)

❌ Wrong

This is an absolute link.
[Page](/players/index)

❌ Wrong

This relative link has the file extension.
[Page](../players/index.md)