Consulter votre README de projet dans Orbit

L'onglet Docs affiche le README de votre référentiel dans KPanel, de sorte que la documentation du projet se trouve à un clic de ses déploiements au lieu d'être dans un onglet du navigateur que quelqu'un doit aller chercher.

Où se trouve l'onglet Docs

Ouvrez Orbit, cliquez sur le projet, puis choisissez Docs sous le groupe Overview dans la bande d'onglets du projet.

Il n'y a rien à configurer. Si le projet dispose d'un référentiel connecté avec un README à sa racine, l'onglet l'affiche.

Quel fichier est affiché

Orbit récupère le README de la branche par défaut du référentiel connecté.

Sur GitHub, il essaie plusieurs noms conventionnels dans l'ordre: README.md, readme.md, README.MD, README, et readme.txt, en prenant le premier qui existe. Sur GitLab et Bitbucket, il recherche README.md.

Seule la racine du référentiel est vérifiée. Un README dans un sous-répertoire, y compris le répertoire racine d'une application monorepo, n'est pas détecté.

Ce qui s'affiche

Le README est affiché en markdown: les titres, les listes, les tableaux, les liens, le code en ligne et les blocs de code délimités s'affichent comme prévu.

Les chemins d'image relatifs dans un README pointent vers le référentiel, non vers KPanel, de sorte que les images qui fonctionnent sur le site de votre fournisseur peuvent ne pas se résoudre ici. Si une image est importante, utilisez une URL absolue.

États vides

Deux états remplacent le contenu quand il n'y a rien à afficher:

• Aucun référentiel connecté, avec un bouton Connecter un référentiel. Connectez-en d'abord un: voir Connexion d'un référentiel GitHub, Connexion d'un référentiel GitLab ou Connexion d'un référentiel Bitbucket.
• Aucun README trouvé, vous invitant à ajouter un README.md à la racine de votre référentiel, avec un lien pour en créer un chez votre fournisseur.

Les deux pointent vers le fournisseur afin que vous puissiez agir immédiatement, et la vue remplie porte un lien Afficher sur vers le fichier lui-même pour lorsque vous souhaitez le modifier.

Écrire un README qui vaut la peine d'être affiché

Parce que cet onglet se trouve à côté de l'historique de déploiement, le README le plus utile pour un projet Orbit est un README opérationnel. Quelqu'un l'ouvre parce qu'on vient de lui confier le projet et qu'il doit changer quelque chose en toute sécurité.

Une structure qui fonctionne:

Ce que c'est. Un paragraphe. Ce que le projet fait et qui il sert.

L'exécuter localement. Les commandes exactes, y compris le gestionnaire de paquets. pnpm install && pnpm dev vaut mieux qu'un paragraphe décrivant la même chose.

Variables d'environnement. Lesquelles existent et à quoi sert chacune. Jamais les valeurs: celles-ci appartiennent aux variables d'environnement du projet, pas à un fichier du référentiel. Voir Variables d'environnement dans Orbit.

Comment cela se déploie. Quelle branche est la production, si les balises se déploient, et quelles portes sont en vigueur. Pointez vers l'onglet Pipeline de déploiement Orbit plutôt que de le dupliquer, car l'onglet ne peut pas devenir obsolète et votre README peut.

Comment revenir en arrière. Deux phrases et un lien vers Revenir en arrière sur un déploiement. C'est ce dont les gens ont besoin dans le pire moment, et c'est là qu'ils vont regarder.

Qui en est propriétaire. Une équipe ou une personne. Les projets survivent aux personnes qui les ont mis en place.

Ajouter un badge d'état en direct

Puisque le README est affiché ici et chez votre fournisseur, un badge d'état de déploiement vaut la peine d'être ajouté. Orbit en publie un pour chaque projet.

Ouvrez Settings et trouvez la fiche Badge d'état. Elle affiche un aperçu en direct et trois boutons de copie: l'URL du badge, un extrait markdown et un extrait HTML. Collez le markdown en haut de votre README.

Le badge est un petit SVG qui rapporte l'état actuel de l'environnement de production du projet: déployé, en construction, échoué, en attente, ou aucun déploiement. Il ne nécessite pas d'authentification, il s'affiche donc pour toute personne lisant le référentiel, et il renvoie au projet dans KPanel.

Cela vous donne un README qui montre, en un coup d'œil, si la production est actuellement saine. C'est la ligne la plus utile que vous puissiez y ajouter.

Rester honnête

Un README qui décrit une configuration que le projet n'a plus est pire que pas de README, car les gens lui font confiance. Deux habitudes le gardent exact:

• Liez plutôt que dupliquer. Tout ce qui est visible dans KPanel, comme les paramètres de compilation, les portes et la configuration de l'environnement, doit être lié à, non pas reformulé.
• Mettez-le à jour dans la même pull request. Si une modification change le fonctionnement du projet, la modification du README appartient à cette pull request, pas à un nettoyage ultérieur.

Dépannage

L'onglet affiche une ancienne version. Le cache de cinq minutes. Attendez et rechargez.

Aucun README trouvé, mais il y en a un. Vérifiez qu'il se trouve à la racine du référentiel et nommé README.md. Sur GitLab et Bitbucket, le nom doit correspondre exactement.

Le référentiel est connecté mais l'onglet dit qu'il ne l'est pas. La connexion peut avoir perdu l'accès, par exemple si l'intégration a été supprimée côté fournisseur. Reconnectez-le à partir des paramètres du projet.

Les images ne se chargent pas. Les chemins relatifs ne se résolvent pas ici. Utilisez des URL absolues.

Le badge affiche aucun déploiement. L'environnement de production n'a jamais eu de déploiement réussi. Déployez une fois et il se met à jour.

Où aller ensuite

• Pipeline de déploiement Orbit, la version en direct de ce qu'un README essaie généralement de décrire.
• Paramètres du projet Orbit pour le badge d'état et le reste de la configuration.
• Variables d'environnement dans Orbit pour les valeurs qu'un README ne doit jamais contenir.