site www
1.0.0
Le site de documentation pour le langage de programmation DART, construit avec Eleventy et hébergé sur Firebase.
Nous accueillons les contributions de toutes sortes! Pour configurer le site localement, suivez les directives ci-dessous sur la construction du site. Pour en savoir plus sur la contribution à ce référentiel, consultez les directives contributives.
Commencez par chercher un problème qui attire votre intérêt ou créez un problème avec votre changement proposé. Envisagez d'ajouter un commentaire pour faire savoir à tout le monde que vous y travaillez et n'hésitez pas à poser toutes les questions que vous avez sur le même problème.
Pour mettre à jour ce site, débarquez le dépôt, apportez vos modifications et générez une demande de traction. Pour les petits changements contenus (tels que le style et les correctifs de faute de frappe), vous n'avez probablement pas besoin de créer ce site. Souvent, vous pouvez apporter des modifications en utilisant l'interface utilisateur GitHub. Nous pouvons mettre en scène les modifications automatiquement dans votre demande de traction.
Important
Si vous clonez ce référentiel localement, suivez l'instruction ci-dessous sur le clonage avec son sous-module.
Si votre modification implique des échantillons de code, ajoute / supprime les pages ou affecte la navigation, envisagez de construire et de tester votre travail avant de soumettre.
Si vous voulez ou avez besoin de construire le site, suivez les étapes ci-dessous.
Pour les modifications au-delà du texte simple et des ajustements CSS, nous vous recommandons d'exécuter le site localement pour activer un cycle d'édition-refresh.
Installez les outils suivants pour créer et développer le site:
La dernière version stable de DART est nécessaire pour construire le site et exécuter son outillage. Cela peut être la fléchette incluse dans le SDK Flutter. Si vous n'avez pas DART ou que vous n'avez pas besoin de mettre à jour, suivez les instructions sur Get the Dart SDK.
Si vous avez déjà installé Dart, vérifiez qu'il est sur votre chemin et déjà la dernière version stable:
dart --version
La dernière version LTS stable de Node.js est nécessaire pour construire le site. Si vous n'avez pas Node.js ou que vous devez mettre à jour, téléchargez la version correspondante de votre ordinateur et suivez les instructions de l'archive de téléchargement de Node.js. Si vous préférez, vous pouvez utiliser un gestionnaire de version tel que NVM et exécuter nvm install à partir du répertoire racine du référentiel.
Si vous avez déjà installé le nœud, vérifiez qu'il est disponible sur votre chemin et déjà la dernière version stable (actuellement 20.14 ou version ultérieure) :
node --version
Si votre version est obsolète, suivez les instructions de mise à jour pour la façon dont vous l'avez installée à l'origine.
Note
Ce référentiel a des sous-modules GIT, ce qui affecte la façon dont vous le clonez. La documentation GitHub a une aide générale sur la fourniture et le clonage des référentiels.
Si vous n'êtes pas membre de l'organisation DART, nous vous recommandons de créer une fourche de ce dépôt sous votre propre compte, puis de soumettre un PR à partir de cette fourche.
Une fois que vous avez une fourche (ou que vous êtes un membre de Dart Org), choisissez l'une des techniques de clonage de sous-module suivantes:
Clone le repo et son sous-module en même temps à l'aide de l'option --recurse-submodules :
git clone --recurse-submodules https://github.com/dart-lang/site-www.git
Si vous avez déjà cloné le repo sans son sous-module, exécutez cette commande à partir de la racine du référentiel:
git submodule update --init --recursive
Note
À tout moment pendant le développement, vous pouvez utiliser la commande git submodule pour rafraîchir les sous-modules:
git pull && git submodule update --init --recursive
Avant de continuer à configurer l'infrastructure du site, vérifiez les versions correctes de Dart et Node.js sont configurées et disponibles en suivant les instructions pour obtenir les conditions préalables.
Facultatif: après le clonage du repo et de ses sous-modules, créez une branche pour vos modifications:
git checkout -b <BRANCH_NAME>
Dans le répertoire racine du référentiel, récupérez les dépendances de fléchettes du site.
dart pub get
Installez pnpm à l'aide de votre méthode d'installation préférée. pnpm est un gestionnaire de packages alternatif et efficace pour les packages NPM. Si vous avez déjà pnpm , vérifiez que vous avez la dernière version stable. Nous vous recommandons d'utiliser corepack pour installer et gérer les versions pnpm , car elle est regroupée avec la plupart des installations de nœud.
Si vous n'avez pas utilisé corepack auparavant, vous devrez d'abord l'activer avec corepack enable . Ensuite, pour installer la version pnpm correcte, à partir du répertoire racine du référentiel, exécutez corepack install :
corepack enable
corepack install
Une fois que vous avez installé et configuré pnpm , récupérez les dépendances NPM du site à l'aide de pnpm install . Nous vous recommandons fortement d'utiliser pnpm , mais vous pouvez également utiliser npm .
pnpm install
Dans le répertoire racine, exécutez l'outil dash_site pour valider votre configuration et découvrir les commandes disponibles.
./dash_site --help
Dans le répertoire racine, servez le site localement.
./dash_site serve
Cette commande génère et sert le site sur un port local imprimé sur votre terminal.
Consultez vos modifications dans le navigateur en naviguant vers http: // localhost: 4000.
Remarque Le port peut être différent si 4000 est pris.
Si vous souhaitez vérifier la sortie et la structure HTML générées et générées, affichez le répertoire _site dans un explorateur de fichiers ou un IDE.
Apportez vos modifications au dépôt local.
Le site doit se reconstruire automatiquement sur la plupart des modifications, mais si quelque chose ne met pas à jour, quittez le processus et réacheminez la commande. Des améliorations à cette fonctionnalité sont prévues. Veuillez ouvrir un nouveau problème pour suivre le problème si cela se produit.
Commentez vos modifications à la succursale et soumettez votre PR.
Si votre changement est important ou si vous souhaitez le tester, envisagez de valider vos modifications.
Conseil
Pour trouver des commandes supplémentaires que vous pouvez exécuter, exécutez ./dash_site --help à partir du répertoire racine du référentiel.
Si vous avez apporté des modifications au code dans les répertoires /examples ou /tool , engagez votre travail, puis exécutez la commande suivante pour vérifier qu'elle est à jour et correspond aux normes du site.
./dash_site check-all
Si ce script signale des erreurs ou des avertissements, résolvez ces problèmes et relâchez la commande. Si vous avez des problèmes, laissez un commentaire sur votre problème ou votre demande de traction, et nous ferons de notre mieux pour vous aider. Vous pouvez également discuter avec nous sur la chaîne #hackers-devrel sur la discorde des contributeurs Flutter!
Une version qui échoue avec l' Error: Some code excerpts needed to be updated! signifie qu'un ou plusieurs extraits de code dans les fichiers de démarque du site ne sont pas identiques aux régions de code déclarées dans les fichiers .dart correspondants.
Pour résoudre cette erreur, à partir de la racine du répertoire du site-www , exécutez ./dash_site refresh-excerpts .
Pour en savoir plus sur la création, l'édition et l'utilisation des extraits de code, consultez la documentation du package Updater Extrat.
Les demandes de traction soumises peuvent être automatiquement mise en scène par un maintieur de site. Si vous souhaitez mettre en scène le site vous-même, vous pouvez créer une version complète et la télécharger sur Firebase.
Si vous n'avez pas déjà de projet Firebase,
Accédez à la console Firebase et créez votre propre projet Firebase (par exemple, dart-dev-staging ).
Retournez vers votre terminal local et vérifiez que vous êtes connecté.
firebase login
Assurez-vous que votre projet existe et activez ce projet:
firebase projects:list
firebase use <your-project>
Dans le répertoire racine du référentiel, créez le site:
./dash_site build
Cela construit le site et le copie dans votre _site local. Si ce répertoire existait précédemment, il sera remplacé.
Déployer sur le site d'hébergement par défaut de votre projet Firebase activé:
firebase deploy --only hosting
Accédez à votre PR sur GitHub et incluez le lien de la version mise en scène. Envisagez d'ajouter une référence à l'engagement que vous avez mis en scène, afin que les examinateurs sachent si d'autres modifications ont été apportées.
