scratch www
2.2.3 Hotfix
Il s'agit du client Web open source de Scratch ! C'est le code d'une grande partie du site Web Scratch.
En particulier, cette base de code comprend du code pour :
Le projet scratch-www comporte de nombreux aspects de sa conception qui sont particuliers à nos systèmes backend. Pour l'utiliser pour votre propre projet, vous devrez examiner tous les endroits où il effectue des appels backend et créer vos propres systèmes backend pour exécuter ces fonctions.
Le projet scratch-gui, quant à lui, est conçu pour pouvoir être utilisé par n'importe qui, sans avoir besoin de créer des systèmes backend, bien qu'il puisse également prendre en charge les systèmes backend pour la sauvegarde des projets et des actifs.
Nous apprécions vos contributions à cette base de code ! Vous souhaiterez peut-être commencer par parcourir la liste actuelle des problèmes ouverts intitulée « aide recherchée ».
Contribuer à scratch-www peut être plus difficile que contribuer à scratch-gui. En effet, scratch-gui peut être exécuté seul, sans nécessiter l'exécution d'autres services, tandis que scratch-www doit communiquer avec plusieurs systèmes backend exécutés par l'équipe Scratch (voir "Comment cela s'intègre-t-il aux autres dépôts Scratch". au-dessus de). Si vous débutez dans la contribution au code source de Scratch, nous vous suggérons de commencer par vous familiariser avec scratch-gui et sa liste de problèmes ouverts intitulés « aide recherchée ».
Pour contribuer, veuillez suivre les étapes standard pour contribuer à un projet sur GitHub.
Voir le fichier LICENSE dans ce référentiel.
Voici quelques ressources pour vous aider à vous familiariser avec la façon dont nous travaillons sur la base de code Scratch :
Les technologies de base importantes utilisées par cette base de code incluent :
Nos tests utilisent :
Assurez-vous d'avoir installé :
Il est important de s'assurer que toutes les dépendances sont à jour car le code scratch-www ne fonctionne qu'avec des versions spécifiques des dépendances. Vous pouvez mettre à jour les packages en utilisant la commande :
npm installCes avertissements peuvent être ignorés en toute sécurité :
npm WARN [email protected] requires a peer of react@^0.14.0 but none was installed.
npm WARN [email protected] requires a peer of react@^0.14.0 but none was installed.
npm WARN [email protected] requires a peer of redux@^2.0.0 || ^3.0.0 but none was installed.
npm WARN [email protected] requires a peer of react@^0.14.7 but none was installed.
npm WARN [email protected] requires a peer of react@^0.14.8 but none was installed.Ceux-ci existent actuellement dans static/js/lib .
Pour compiler le code source en bundles HTML et JavaScript que les navigateurs peuvent lire, vous pouvez créer une version temporaire du site sur votre ordinateur à laquelle vous pouvez accéder via votre navigateur Web.
Vous pouvez soit "construire" le site une seule fois, en exécutant :
npm run buildVous pouvez également exécuter un serveur qui reconstruit les fichiers au fur et à mesure que vous les modifiez, en exécutant les commandes :
npm run translate
npm start REMARQUE : npm run translate crée le répertoire intl. Le site se construira correctement sans cela, mais les chaînes de texte traduisibles ne s'afficheront pas correctement tant que vous n'aurez pas créé intl.
Pendant le développement, npm start surveille toute mise à jour que vous effectuez sur les fichiers dans ./static ou ./src et déclenche une reconstruction du projet. En développement, la build est stockée en mémoire et n'est pas servie à partir du répertoire ./build .
Une fois que vous avez créé le site local, à l'aide de npm run build ou npm start , le site hébergé sur votre ordinateur local est accessible par un navigateur Web en entrant localhost:8333 dans la barre d'adresse de votre navigateur.
Lors de l'exécution npm start , voici quelques messages de journal importants à surveiller :
webpack: bundle is now VALID. – Le bundle a été chargé en mémoire et est désormais visible dans le navigateur. Cela apparaîtra à la fois une fois que npm start aura terminé sa configuration, ainsi qu'une fois que les mises à jour que vous apporterez aux fichiers auront été recompilées pour être affichées dans le navigateur.webpack: bundle is now INVALID. – Si vous voyez cela, cela signifie que vous avez mis à jour les fichiers qui sont encore en cours de compilation pour être visualisés par le navigateur. Les pages seront toujours visibles, mais elles ne verront pas encore les mises à jour que vous avez effectuées. Pour arrêter le processus npm start qui rend le site disponible pour votre navigateur Web (créé ci-dessus dans « Pour construire »), utilisez ^C (control-c) dans le terminal.
npm start peut être configuré avec les variables d'environnement suivantes, en les définissant au début de la commande, avant npm start :
| Variable | Défaut | Description |
|---|---|---|
API_HOST | https://api.scratch.mit.edu | Nom d'hôte pour les requêtes API |
ASSET_HOST | https://assets.scratch.mit.edu | Nom d'hôte pour les demandes d'actifs |
BACKPACK_HOST | https://backpack.scratch.mit.edu | Nom d'hôte pour les demandes de sac à dos |
PROJECT_HOST | https://projects.scratch.mit.edu | Nom d'hôte pour les demandes de projet |
FALLBACK | '' | Emplacement de passage pour ancien site |
THUMBNAIL_URI | /internalapi/project/thumbnail/{}/set/ | Modèle d'URI pour la mise à jour des vignettes du projet, {} est remplacé par l'ID du projet lors de l'appel d'une requête |
THUMBNAIL_HOST | '' | Nom d'hôte du service de téléchargement |
GTM_ID | '' | Identifiant Google Tag Manager |
GTM_ENV_AUTH | '' | Informations d'environnement et d'authentification de Google Tag Manager |
NODE_ENV | null | Si ce n'est pas production , l'application agit comme un développement |
PORT | 8333 | Port pour le serveur de développement (http://localhost:XXXX) |
REMARQUE : étant donné que par défaut API_HOST=https://api.scratch.mit.edu , sachez que, par défaut, vous verrez et interagirez avec des données réelles sur le site Web Scratch.
La plupart de nos tests unitaires s'exécutent avec Jest, mais les anciens tests unitaires utilisent le framework TAP.
Pour créer l'application et exécuter tous les tests unitaires et de localisation, utilisez la commande :
npm test Pour exécuter un seul fichier de test unitaire à partir de la ligne de commande à l'aide de Jest, utilisez la commande :
node_modules/.bin/jest ./test/unit/PATH/TO/FILENAME.test.js REMARQUE : remplacez PATH/TO/FILENAME par le chemin réel du fichier que vous souhaitez exécuter.
Nos tests d'intégration supposent qu'un environnement plus vaste que le simple scratch-www fonctionne seul ; par exemple, beaucoup exigent qu'un utilisateur test puisse se connecter au site, ce qui nécessite une prise en charge du backend et de la base de données.
Par défaut, les tests sont exécutés sur notre instance Staging, mais vous pouvez les transmettre à un emplacement différent avec la variable d'environnement ROOT_URL (voir ci-dessous) si vous souhaitez exécuter les tests sur un autre emplacement, par exemple votre build local.
Tous nos tests d'intégration utilisent Jest comme cadre de test.
Pour exécuter tous les tests d'intégration à partir de la ligne de commande :
SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu UNOWNED_SHARED_PROJECT_ID= # UNOWNED_UNSHARED_PROJECT_ID=# OWNED_SHARED_PROJECT_ID=# OWNED_UNSHARED_PROJECT_ID=# npm run test:integration Les tests utilisent plusieurs utilisateurs avec des noms d'utilisateur similaires et le même mot de passe. Ils utilisent le nom d'utilisateur que vous transmettez avec SMOKE_USERNAME ainsi que le même nom d'utilisateur avec 1, 2, 3, 4, 5 et 6 (bientôt des nombres plus élevés) ajoutés à la fin. Donc, si vous utilisez le nom d'utilisateur "test", il utilisera également le nom d'utilisateur "test1", "test2", "test3", etc. Assurez-vous d'avoir créé des comptes avec ce modèle et d'utiliser le même mot de passe pour tous les comptes impliqués.
Vous pouvez utiliser n’importe quel ensemble de noms d’utilisateur correspondant à ce modèle. Chaque compte doit partager le même mot de passe, qui est transmis sous la forme SMOKE_PASSWORD.
Plusieurs variables d'environnement doivent être transmises pour que les tests s'exécutent. La plupart d’entre eux ont des valeurs par défaut qui pointent vers le serveur intermédiaire.
Pour exécuter un seul fichier à partir de la ligne de commande à l'aide de Jest :
SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu node_modules/.bin/jest ./test/integration/filename.test.jsPour exécuter un seul fichier à partir de la ligne de commande à l'aide de TAP :
SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu node_modules/.bin/tap ./test/integration-legacy/smoke-testing/filename.js -R classic --no-coverage --timeout=3600-R classic fait que tap utilise l'ancien style de reporting, ce qui évite une erreur avec le package "nyc"--no-coverage est dû au fait que nous n'utilisons pas la fonction de suivi de couverture de Taptimeout correspond à la durée de toute la suite de tests de tap ; si vous obtenez une erreur de délai d'attente, vous devrez peut-être ajuster cette valeur (certains tests Selenium prennent un certain temps à s'exécuter) Les tests d'intégration peuvent être exécutés à l'aide de Saucelabs, un service en ligne qui permet de tester à distance plusieurs combinaisons navigateur/OS. (Actuellement, tous les tests sont écrits pour être utilisés pour Chrome sur Mac).
Vous aurez besoin d'un compte Saucelabs pour pouvoir l'utiliser à des fins de tests. Si vous en avez une, vous pouvez trouver votre clé d'accès :
Pour exécuter des tests à l'aide de Saucelabs, exécutez la commande :
SMOKE_USERNAME=username SMOKE_PASSWORD=password SAUCE_USERNAME=saucelabsUsername SAUCE_ACCESS_KEY=saucelabsAccessKey ROOT_URL=https://scratch.mit.edu npm run test:integration:remoteREMARQUE : actuellement, les tests Jest ne s'exécuteront pas avec Saucelabs.
| Variable | Défaut | Description |
|---|---|---|
ROOT_URL | scratch.ly | Emplacement sur lequel vous souhaitez exécuter les tests |
SMOKE_USERNAME | None | Nom d'utilisateur de l'utilisateur Scratch avec lequel vous vous connectez pour tester |
SMOKE_PASSWORD | None | Mot de passe de l'utilisateur Scratch avec lequel vous vous connectez pour tester |
SMOKE_REMOTE | false | Tests avec Sauce Labs ou non. Vrai si test:smoke:sauce est en cours d'exécution |
SMOKE_HEADLESS | false | Exécutez le navigateur en mode sans tête. Floquant pour le moment |
SAUCE_USERNAME | None | Nom d'utilisateur pour votre compte Sauce Labs |
SAUCE_ACCESS_KEY | None | Clé d'accès pour Sauce Labs trouvée sous Paramètres utilisateur |
Le déploiement vers la préparation ou la production téléchargera le code sur S3 et configurera Fastly.
npm install
virtualenv ENV
. ENV/bin/activate
pip install -r requirements.txt
npm run build && npm run deploy| Variable | Défaut | Description |
|---|---|---|
FASTLY_SERVICE_ID | '' | ID de service Fastly pour bin/configure-fastly.js |
FASTLY_API_KEY | '' | Clé API Fastly pour bin/configure-fastly.js |
FASTLY_ACTIVATE_CHANGES | false | Activer les modifications et purger tout après la configuration |
AWS_ACCESS_KEY_ID | '' | ID de clé d'accès AWS pour S3 |
AWS_SECRET_ACCESS_KEY | '' | Clé d'accès secrète AWS pour S3 |
S3_BUCKET_NAME | '' | Nom du compartiment S3 dans lequel déployer |
Lors du déploiement, l'API de Fastly est utilisée pour cloner la configuration VCL active, mettre à jour uniquement le composant pertinent avec le contenu du fichier routes.json de ce référentiel et activer la nouvelle configuration VCL.
Une grande partie du fichier routes.json est simple, mais certains champs ne sont pas évidents dans leur objectif.
routeAlias nous aide à éviter que la longueur globale et la complexité du code de comparaison d'expression régulière dans Fastly ne deviennent trop volumineuses. Il existe une grande expression régulière avec laquelle nous testons rapidement l'URL de la demande entrante pour savoir si elle peut répondre avec un fichier statique dans S3 ; si aucune correspondance n'est trouvée, nous supposons que nous devons transmettre la requête à scratchr2. Nous pourrions tester chaque expression régulière pattern de route dans routes.json , mais beaucoup sont similaires, nous prenons donc simplement l'ensemble unique de toutes les entrées routeAlias , qui est plus court et plus rapide.
Pour le développement sous Windows, vous devrez probablement utiliser un programme qui vous fournit une interface Unix.
Il existe plusieurs options pour ce faire :
De plus, vous devrez installer Node ; voici les instructions pour installer Node sur WSL.
Nous sommes actuellement en train de passer à ce client Web à partir de la structure existante de Scratch. Au cours de notre transition, nous rencontrerons certains problèmes liés à la manière dont ce client doit interagir avec l'infrastructure existante pour fonctionner correctement en production.
En plus de migrer vers cette utilisation en tant que client Web, Scratch utilise également un nouveau backend d'API, l'API Scratch REST (source fermée). Comme cela est également actuellement en développement et incomplet, nous sommes configurés pour recourir aux points de terminaison Scratch existants si aucun point de terminaison d'API n'existe - c'est là qu'intervient le FALLBACK .
La plupart des problèmes que nous rencontrons actuellement tournent autour de l'utilisation de FALLBACK . Cette variable est utilisée pour spécifier sur quelle URL recourir en cas d'échec d'une requête dans le contexte de ce client Web ou lors de l'utilisation de API_HOST . S'il n'est pas spécifié dans le processus, il ne sera pas utilisé et toute demande qui n'est pas effectuée via le client Web ou l'API sera inaccessible.
Le paramètre FALLBACK=https://scratch.mit.edu permet au client Web de récupérer les données du site Web Scratch dans votre environnement de développement. Cependant, pour des raisons de sécurité, essayer d'envoyer des données à Scratch via votre environnement de développement ne fonctionnera pas. Cela signifie que les éléments suivants seront interrompus pour le moment :
De plus, si vous définissez FALLBACK=https://scratch.mit.edu , sachez que cliquer sur des liens vers des parties du site Web qui n'ont pas encore migré (actuellement telles que Discuss , Profile , My Stuff , etc.) vous amènera à le site Web Scratch lui-même.
