Linee Guida per la Contribuzione 1.21.8

Linee guida per le contribuzioni alla Documentazione di Fabric.

WARNING

Questa pagina si applica alla versione 1.21.8. La documentazione delle versioni meno recenti potrebbe essere incompleta.

Questo sito usa VitePress per generare HTML statico da vari file Markdown. Dovresti familiarizzare con le estensioni per Markdown che VitePress supporta qui.

Ci sono tre modi per contribuire a questo sito:

• Tradurre la Documentazione
• Contribuire con Contenuti
• Contribuire al Framework

Tutte le contribuzioni devono seguire le nostre linee guida per lo stile.

Tradurre la Documentazione

Se vuoi tradurre la documentazione nella tua lingua, puoi farlo nella pagina Crowdin di Fabric.

new-content Contribuire con Contenuti

Le contribuzioni con contenuti sono il modo principale per contribuire alla Documentazione di Fabric.

Tutte le contribuzioni con contenuti passano per le seguenti fasi, ciascuna delle quali è associata ad un'etichetta:

1. localmente Prepara le tue modifiche e apri una PR
2. stage:expansion Indicazioni per l'espansione se necessaria
3. stage:verification: Verifica dei contenuti
4. stage:cleanup: Grammatica, Linting...
5. stage:ready: Pronta per il merge!

Tutto il contenuto deve rispettare le nostre linee guida per lo stile.

1. Prepara le Tue Modifiche

Il sito è open-source, ed è sviluppato in una repository su GitHub, il che significa che ci affidiamo al flow GitHub:

1. Crea una fork della Repository su GitHub
2. Crea un nuovo branch sulla tua fork
3. Aggiungi le tue modifiche su quel branch
4. Apri una Pull Request alla repository originale

Puoi leggere di più riguardo al flow GitHub qui.

È possibile fare modifiche dall'interfaccia web su GitHub, oppure puoi sviluppare e ottenere un'anteprima del sito localmente.

Clonare la Tua Fork

Se vuoi sviluppare localmente, dovrai installare Git.

Dopo di che, clona la tua fork della repository con:

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

Installare le Dipendenze

Se vuoi ottenere un'anteprima locale delle tue modifiche, dovrai installare Node.js 18+.

Dopo di che, assicurati di installare tutte le dipendenze con:

npm install

Eseguire il Server di Sviluppo

Questo di permetterà di ottenere un'anteprima locale delle tue modifiche presso localhost:5173 e ricaricherà automaticamente la pagina quando farai modifiche.

npm run dev

Ora puoi aprire e navigare sul sito dal browser visitando http://localhost:5173.

Costruire il Sito

Questo compilerà tutti i file Markdown in HTML statico e li posizionerà in .vitepress/dist:

npm run build

Ottenere un'Anteprima del Sito Costruito

Questo avvierà un server locale in porta 4173 che servirà il contenuto trovato in .vitepress/dist:

npm run preview

Aprire una Pull Request

Quando sarai felice delle tue modifiche, puoi fare push delle tue modifiche:

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

Dopo di che segui il link nell'output di git push per aprire una PR.

2. stage:expansion Indicazioni per l'Espansione Se Necessaria

Se il team della documentazione crede che tu possa espandere la tua pull request, un membro del team aggiungerà l'etichetta stage:expansion alla tua pull request assieme a un commento che spiega cosa credono che tu possa espandere. Se sei d'accordo con il consiglio, puoi espandere la tua pull request.

Se non vuoi espandere la tua pull request, ma ti va bene che qualcun altro lo faccia successivamente, dovresti creare un'issue sulla pagina Issues e spiegare cosa credi che si possa espandere. Il team di documentazione aggiungerà quindi l'etichetta help-wanted alla tua PR.

3. stage:verification Verifica dei Contenuti

Questa è la fase più importante poiché assicura che il contenuto sia accurato e segua le linee guida per lo stile della Documentazione di Fabric.

In questa fase, bisognerebbe rispondere alle seguenti domande:

• Il contenuto è tutto corretto?
• Il contenuto è tutto aggiornato?
• Il contenuto copre tutti i casi possibili, per esempio i vari sistemi operativi?

4. stage:cleanup: Pulizia

In questa fase, avviene ciò che segue:

• Correzione di eventuali errori grammaticali tramite LanguageTool
• Linting di tutti i file Markdown tramite markdownlint
• Formattazione di tutto il codice Java tramite Checkstyle
• Altri cambiamenti o miglioramenti vari

framework Contribuire al Framework

Framework si riferisce alla struttura interna del sito, ogni pull request che modifica il framework del sito dovrebbe essere etichettata con l'etichetta framework.

Dovresti davvero fare pull request riguardanti il framework solo dopo esserti consultato con il team della documentazione nel Discord di Fabric o tramite un'issue.

INFO

Modificare i file nella sidebar e la configurazione della barra di navigazione non conta come pull request riguardante il framework.

Linee Guida per lo Stile

Se fossi incerto riguardo a qualsiasi cosa, puoi chiedere nel Discord di Fabric o tramite GitHub Discussions.

Scrivi l'Originale in Inglese Americano

Tutta la documentazione originale è scritta in Inglese, seguendo le regole grammaticali americane.

Aggiungi i Dati al Frontmatter

Ogni pagina deve avere un titolo (title) e una descrizione (description) nel frontmatter.

Ricordati anche di aggiungere il tuo nome utente GitHub ad authors nel frontmatter del file Markdown! In questo modo possiamo darti l'attribuzione che meriti.

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

Aggiungi Ancore alle Intestazioni

Ogni intestazione deve avere un'ancora, che viene usata per collegarsi a quell'intestazione:

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

L'ancora deve usare caratteri minuscoli, numeri e trattini.

Posiziona il Codice Nella Mod /reference

Se crei o modifichi pagine contenenti codice, metti il codice in una posizione appropriata nella mod reference (presente nella cartella /reference della repository). Dopo di che, usa la funzione code snippet fornita da VitePress per incorporare il codice.

Per esempio, per evidenziare le linee 15-21 del file FabricDocsReference.java dalla mod reference:

md

<<< @/reference/1.21.8/src/main/java/com/example/docs/FabricDocsReference.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.ResourceLocation;

import net.fabricmc.api.ModInitializer;
import net.fabricmc.fabric.api.item.v1.ComponentTooltipAppenderRegistry;
import net.fabricmc.fabric.api.particle.v1.FabricParticleTypes;

import com.example.docs.component.ModComponents;

//#entrypoint
public class FabricDocsReference 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 = "fabric-docs-reference";
	public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);

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

	//#particle_register_main
	//#entrypoint
	@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!");
		//#entrypoint

		//#particle_register_main
		// Register our custom particle type in the mod initializer.
		Registry.register(BuiltInRegistries.PARTICLE_TYPE, ResourceLocation.fromNamespaceAndPath(MOD_ID, "sparkle_particle"), SPARKLE_PARTICLE);
		//#particle_register_main
		//#entrypoint

		// #tooltip_provider
		ComponentTooltipAppenderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.COMPONENT_WITH_TOOLTIP);
		// #tooltip_provider
	}
}

Se ti serve un controllo più raffinato, puoi usare la funzione transclude da markdown-it-vuepress-code-snippet-enhanced.

Per esempio, questo incorporerà le sezioni del suddetto file che sono contrassegnate con il tag #entrypoint:

md

@[code transcludeWith=#entrypoint](@/reference/1.21.8/src/main/java/com/example/docs/FabricDocsReference.java)

java

public class FabricDocsReference 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 = "fabric-docs-reference";
	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!");

		// #tooltip_provider
		ComponentTooltipAppenderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.COMPONENT_WITH_TOOLTIP);
		// #tooltip_provider
	}
}

Crea una Barra Laterale per Ogni Nuova Sezione

Se stai creando una nuova sezione, dovresti creare una nuova barra laterale nella cartella .vitepress/sidebars ed aggiungerla al file i18n.ts.

Se hai bisogno di assistenza con questo, chiedi per favore nel canale #docs del Discord di Fabric.

Aggiungi Nuove Pagine alle Barre Laterali Appropriate

Quando crei una nuova pagina, dovresti aggiungerla alla barra laterale appropriata nella cartella .vitepress/sidebars.

Di nuovo, se hai bisogno di assistenza, chiedi nel canale #docs del Discord di Fabric.

Posiziona i Contenuti Multimediali in /assets

Ogni immagine dovrebbe essere messa in una posizione appropriata nella cartella /public/assets/.

Usa Link Relativi!

Questo è dovuto al sistema di gestione delle versioni in uso, che processerà i link per aggiungerci la versione anticipatamente. Se usassi link assoluti, il numero di versione non verrebbe aggiunto al link.

Devi anche non aggiungere l'estensione del file al link.

Per esempio, per inserire un link alla pagina /players/index.md dalla pagina /develop/index.md, dovresti fare il seguente:

✅ 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)