Visualizzazione del tuo Project README in Orbit

The Docs tab renders your repository's README inside KPanel, so the project's own documentation is one click from its deployments instead of in a browser tab someone has to go and find.

La scheda Docs renderizza il README del tuo repository dentro a KPanel, così la documentazione del progetto è a un click dai suoi deployment invece di trovarsi in una scheda del browser che qualcuno deve andare a cercare.

Dove si trova la scheda Docs

Apri Orbit, fai clic sul progetto e scegli Docs sotto il gruppo Overview nella striscia di schede del progetto.

Non c'è nulla da configurare. Se il progetto ha un repository connesso con un README nella radice, la scheda lo renderizza.

Quale file viene mostrato

Orbit recupera il README dal ramo predefinito del repository connesso.

Su GitHub prova diversi nomi convenzionali in sequenza: README.md, readme.md, README.MD, README e readme.txt, usando il primo che esiste. Su GitLab e Bitbucket cerca README.md.

Solo la radice del repository viene verificata. Un README all'interno di una sottodirectory, inclusa la directory root di un'app monorepo, non viene rilevato.

Il contenuto viene memorizzato nella cache per circa cinque minuti. Se esegui il push di una modifica al tuo README, la scheda mostrerà comunque il testo precedente brevemente. È normale; aspetta e ricarica invece di supporre che la modifica non sia stata applicata.

Cosa viene renderizzato

Il README viene renderizzato come markdown: titoli, elenchi, tabelle, link, codice inline e blocchi di codice delimitati si visualizzano come previsto.

I percorsi di immagine relativi all'interno di un README puntano al repository, non a KPanel, quindi le immagini che funzionano sul sito del tuo provider potrebbero non risolversi qui. Se un'immagine è importante, usa un URL assoluto.

Stati vuoti

Due stati sostituiscono il contenuto quando non c'è nulla da mostrare:

No repository connected (Nessun repository connesso), con un pulsante Connect repository (Connetti repository). Connettine uno prima: vedi Connecting a GitHub Repository, Connecting a GitLab Repository o Connecting a Bitbucket Repository.
No README found (README non trovato), che ti invita ad aggiungere un README.md nella radice del tuo repository, con un link per crearne uno sul tuo provider.

Entrambi rimandano al provider per poter agire immediatamente, e la visualizzazione popolata include un link View on al file stesso per quando vuoi modificarlo.

Scrivere un README che valga la pena renderizzare

Poiché questa scheda si trova accanto alla cronologia dei deploy, il README più utile per un progetto Orbit è uno operazionale. Qualcuno lo apre perché gli è stato appena assegnato il progetto e ha bisogno di cambiare qualcosa in sicurezza.

Una struttura che funziona:

What this is. Un paragrafo. Cosa fa il progetto e chi serve.

Running it locally. I comandi esatti, incluso il package manager. pnpm install && pnpm dev è meglio di un paragrafo che descrive la stessa cosa.

Environment variables. Quali esistono e a cosa serve ognuna. Mai i valori: quelli appartengono alle variabili di ambiente del progetto, non a un file nel repository. Vedi Environment Variables in Orbit.

How it deploys. Quale branch è production, se i tag vengono deployati e quali gate sono in vigore. Rimanda alla scheda Orbit Deployment Pipeline invece di duplicarla, perché la scheda non può diventare obsoleta mentre il tuo README sì.

How to roll back. Due frasi e un link a Rolling Back a Deployment. È la cosa di cui le persone hanno bisogno nel loro momento peggiore, e deve trovarsi dove la cercheranno.

Who owns it. Un team o una persona. I progetti sopravvivono alle persone che li hanno creati.

Non inserire mai credenziali in un README. Una stringa di connessione, una chiave API o una password committate in un repository rimangono nella cronologia permanentemente, e eliminarle in un commit successivo non le rimuove. Se è accaduto, ruota la credenziale invece di cercare di ripulire la cronologia.

Aggiungere un badge di stato attivo

Poiché il README viene renderizzato qui e sul tuo provider, vale la pena aggiungere un badge di stato del deploy. Orbit ne pubblica uno per ogni progetto.

Apri Settings e trova la scheda Status badge. Mostra un'anteprima dal vivo e tre pulsanti di copia: l'URL del badge, uno snippet markdown e uno snippet HTML. Incolla il markdown in cima al tuo README.

Il badge è un piccolo SVG che riporta lo stato attuale dell'ambiente production del progetto: deployed, building, failed, queued o no deployments. Non richiede autenticazione, quindi si renderizza per chiunque legga il repository, e rimanda al progetto in KPanel.

Questo ti dà un README che mostra, a colpo d'occhio, se la production è attualmente sana. È la riga di più alto valore singolo che puoi aggiungervi.

Mantenerlo onesto

Un README che descrive una configurazione che il progetto non ha più è peggio di nessun README, perché le persone si fidano di esso. Due abitudini lo mantengono accurato:

Link rather than duplicate. Qualsiasi cosa visibile in KPanel, come le impostazioni di build, i gate e la configurazione dell'ambiente, dovrebbe essere linkato, non reiterato.
Update it in the same pull request. Se una modifica altera il modo in cui il progetto viene eseguito, la modifica del README appartiene a quel pull request, non a una pulizia successiva.

Troubleshooting

The tab shows an old version. La cache di cinque minuti. Aspetta e ricarica.

No README found, but there is one. Verifica che sia nella radice del repository e denominato README.md. Su GitLab e Bitbucket il nome deve corrispondere esattamente.

The repository is connected but the tab says it is not. La connessione potrebbe aver perso l'accesso, ad esempio se l'integrazione è stata rimossa dal lato provider. Riconnettila dalle impostazioni del progetto.

Images do not load. I percorsi relativi non si risolvono qui. Usa URL assoluti.

The badge shows no deployments. L'ambiente production non ha mai avuto un deployment riuscito. Esegui un deploy una volta e si aggiorna.

Dove andare dopo

Orbit Deployment Pipeline, la versione dal vivo di ciò che un README di solito prova a descrivere.
Orbit Project Settings per il badge di stato e il resto della configurazione.
Environment Variables in Orbit per i valori che un README non deve mai contenere.