これは Scratch のオープンソース Web クライアントです。これは、Scratch Web サイトの大部分のコードです。
特に、このコードベースには次のコードが含まれています。
Scratch-www プロジェクトには、バックエンド システムに特有の設計面が数多くあります。これを独自のプロジェクトに使用するには、バックエンド呼び出しを行うすべての場所を確認し、それらの機能を実行する独自のバックエンド システムを作成する必要があります。
一方、scratch-gui プロジェクトは、バックエンド システムを作成する必要がなく、誰でも使用できるように設計されていますが、プロジェクトとアセットの保存のためのバックエンド システムもサポートできます。
このコードベースへの貢献を歓迎します。まずは、「助けを求めています」というラベルが付いた未解決の問題の現在のリストを参照してみるとよいでしょう。
Scratch-www に貢献することは、scratch-gui に貢献することよりも難しい場合があります。これは、scratch-gui は他のサービスを実行する必要がなく単独で実行できるのに対し、scratch-www は Scratch チームが実行する複数のバックエンド システムと通信する必要があるためです (「これが他の Scratch リポジトリとどのように適合するか」を参照)その上)。 Scratch のソース コードに貢献するのが初めての場合は、scratch-gui と「ヘルプ募集」とラベル付けされた未解決の問題のリストに慣れることから始めることをお勧めします。
貢献するには、GitHub 上のプロジェクトに貢献するための標準手順に従ってください。
このリポジトリの LICENSE ファイルを参照してください。
私たちが Scratch コードベースでどのように取り組んでいるかを理解するのに役立つリソースをいくつか紹介します。
このコードベースが使用する重要なコア テクノロジには次のものがあります。
私たちのテストでは以下を使用します。
以下がインストールされていることを確認してください。
スクラッチ www コードは特定のバージョンの依存関係でのみ機能するため、すべての依存関係が最新であることを確認することが重要です。次のコマンドを使用してパッケージを更新できます。
npm install
これらの警告は無視しても問題ありません。
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.
これらは現在 static/js/lib に存在します。
ソース コードをブラウザが読み取れる HTML および JavaScript バンドルにコンパイルするには、Web ブラウザ経由でアクセスできるサイトの一時バージョンをマシン上に作成します。
次のコマンドを実行して、サイトを 1 回だけ「構築」することもできます。
npm run build
または、次のコマンドを実行して、ファイルの編集時にファイルを再構築するサーバーを実行できます。
npm run translate
npm start
注: npm run translate
intl ディレクトリを構築します。サイトはこれなしでも問題なく構築できますが、翻訳可能なテキスト文字列は intl を構築するまで正しく表示されません。
開発中、 npm start
./static
または./src
内のファイルに対する更新を監視し、プロジェクトのリビルドをトリガーします。開発中、ビルドはメモリに保存され、 ./build
build ディレクトリからは提供されません。
npm run build
またはnpm start
を使用してローカル サイトを構築したら、ブラウザのアドレス バーにlocalhost:8333
と入力すると、Web ブラウザからローカル マシンでホストされているサイトにアクセスできます。
npm start
実行するときは、注意すべき重要なログ メッセージがいくつかあります。
webpack: bundle is now VALID.
– バンドルがメモリにロードされ、ブラウザで表示できるようになりました。これは、 npm start
のセットアップが完了したときと、ファイルに加えた更新がブラウザで表示するために再コンパイルされたときの両方に表示されます。webpack: bundle is now INVALID.
– これが表示された場合は、ブラウザで表示するためにまだコンパイル中のファイルに更新を行ったことを意味します。ページは引き続き表示できますが、まだ行った更新は表示されません。Web ブラウザでサイトを利用できるようにするnpm start
プロセス (上記の「ビルドするには」で作成) を停止するには、ターミナルで^C
(control-c) を使用します。
npm start
、コマンドの先頭でnpm start
前に設定することで、次の環境変数を使用して構成できます。
変数 | デフォルト | 説明 |
---|---|---|
API_HOST | https://api.scratch.mit.edu | APIリクエストのホスト名 |
ASSET_HOST | https://assets.scratch.mit.edu | アセットリクエストのホスト名 |
BACKPACK_HOST | https://backpack.scratch.mit.edu | バックパックリクエストのホスト名 |
PROJECT_HOST | https://projects.scratch.mit.edu | プロジェクトリクエストのホスト名 |
FALLBACK | '' | 旧サイトのパススルー位置 |
THUMBNAIL_URI | /internalapi/project/thumbnail/{}/set/ | プロジェクトのサムネイルを更新するための URI テンプレート。リクエストを呼び出すとき、 {} プロジェクト ID に置き換えられます。 |
THUMBNAIL_HOST | '' | アップローダー サービスのホスト名 |
GTM_ID | '' | GoogleタグマネージャーID |
GTM_ENV_AUTH | '' | Google タグ マネージャーの環境と認証情報 |
NODE_ENV | null | production ではない場合、アプリは開発のように動作します |
PORT | 8333 | 開発サーバーのポート (http://localhost:XXXX) |
注: デフォルトではAPI_HOST=https://api.scratch.mit.edu
であるため、デフォルトでは Scratch Web サイト上の実際のデータを表示して操作することになることに注意してください。
ほとんどの単体テストは Jest を使用して実行されますが、古い単体テストは TAP フレームワークを使用します。
アプリケーションを構築し、すべての単体テストとローカリゼーション テストを実行するには、次のコマンドを使用します。
npm test
Jest を使用してコマンドラインから単一の単体テスト ファイルを実行するには、次のコマンドを使用します。
node_modules/.bin/jest ./test/unit/PATH/TO/FILENAME.test.js
注: PATH/TO/FILENAME
実行するファイルへの実際のパスに置き換えます。
私たちの統合テストは、単独でのScratch-wwwよりも大規模な環境が実行されていることを前提としています。たとえば、多くの場合、テスト ユーザーがサイトにログインできることが必要であり、これにはバックエンドとデータベースのサポートが必要です。
デフォルトでは、テストはステージング インスタンスに対して実行されますが、別の場所 (ローカル ビルドなど) に対してテストを実行したい場合は、ROOT_URL 環境変数 (以下を参照) を使用して別の場所を渡すことができます。
すべての統合テストでは、テスト フレームワークとして Jest を使用します。
コマンドラインからすべての統合テストを実行するには:
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
テストでは、同様のユーザー名と同じパスワードを持つ複数のユーザーを使用します。これらは、SMOKE_USERNAME で渡したユーザー名と、同じユーザー名の末尾に 1、2、3、4、5、6 (すぐにこれより大きな数字も追加される予定) を追加したものを使用します。したがって、ユーザー名「test」を使用すると、ユーザー名「test1」、「test2」、「test3」なども使用されます。このパターンでアカウントを作成していることを確認し、関係するすべてのアカウントに同じパスワードを使用してください。
このパターンに適合する任意のユーザー名のセットを使用できます。各アカウントは同じパスワードを共有する必要があり、そのパスワードは SMOKE_PASSWORD として渡されます。
テストを実行するには、いくつかの環境変数を渡す必要があります。それらのほとんどには、ステージング サーバーを指すデフォルトがあります。
Jest を使用してコマンドラインから単一のファイルを実行するには:
SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu node_modules/.bin/jest ./test/integration/filename.test.js
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
タップで古いレポート スタイルが使用されるようになり、「nyc」パッケージでのエラーが回避されます。--no-coverage
、tap のカバレッジ追跡機能を使用していないためです。timeout
引数はタップ テスト スイート全体の長さです。タイムアウト エラーが発生した場合は、この値を調整する必要がある場合があります (Selenium テストの一部は実行に時間がかかります)。 統合テストは、複数のブラウザと OS の組み合わせをリモートでテストできるオンライン サービスである Saucelabs を使用して実行できます。 (現在、すべてのテストは Mac 上の Chrome で使用するために作成されています)。
テストに使用するには、Saucelabs アカウントが必要です。アクセス キーをお持ちの場合は、次の手順でアクセス キーを見つけることができます。
Saucelabs を使用してテストを実行するには、次のコマンドを実行します。
SMOKE_USERNAME=username SMOKE_PASSWORD=password SAUCE_USERNAME=saucelabsUsername SAUCE_ACCESS_KEY=saucelabsAccessKey ROOT_URL=https://scratch.mit.edu npm run test:integration:remote
注: 現在、Jest テストは Saucelabs では実行されません。
変数 | デフォルト | 説明 |
---|---|---|
ROOT_URL | scratch.ly | テストを実行する場所 |
SMOKE_USERNAME | None | テストのためにサインインしている Scratch ユーザーのユーザー名 |
SMOKE_PASSWORD | None | テストのためにサインインしている Scratch ユーザーのパスワード |
SMOKE_REMOTE | false | Sauce Labs を使用してテストするかどうか。 test:smoke:sauce を実行している場合は True |
SMOKE_HEADLESS | false | ブラウザをヘッドレス モードで実行します。現時点では不安定です |
SAUCE_USERNAME | None | Sauce Labs アカウントのユーザー名 |
SAUCE_ACCESS_KEY | None | ユーザー設定の下にある Sauce Labs のアクセス キー |
ステージングまたは本番環境にデプロイすると、コードが S3 にアップロードされ、Fastly が構成されます。
npm install
virtualenv ENV
. ENV/bin/activate
pip install -r requirements.txt
npm run build && npm run deploy
変数 | デフォルト | 説明 |
---|---|---|
FASTLY_SERVICE_ID | '' | bin/configure-fastly.js の Fastly サービス ID |
FASTLY_API_KEY | '' | bin/configure-fastly.js の Fastly API キー |
FASTLY_ACTIVATE_CHANGES | false | 変更をアクティブ化し、構成後にすべてをパージします |
AWS_ACCESS_KEY_ID | '' | S3 の AWS アクセス キー ID |
AWS_SECRET_ACCESS_KEY | '' | S3 の AWS シークレット アクセス キー |
S3_BUCKET_NAME | '' | デプロイ先の S3 バケット名 |
デプロイ時に、Fastly の API を使用してアクティブな VCL 構成のクローンを作成し、このリポジトリのroutes.json
ファイルのコンテンツで関連コンポーネントのみを更新し、新しい VCL 構成をアクティブ化します。
Routes.json ファイルの大部分は単純ですが、一部のフィールドはその目的が明確ではありません。
routeAlias
、Fastly の正規表現比較コード全体の長さと複雑さが大きくなりすぎるのを防ぐのに役立ちます。大きな正規表現が 1 つあり、S3 の静的ファイルで応答できるかどうかを確認するために、受信リクエスト URL を Fastly テストしました。一致するものが見つからない場合は、リクエストをscratchr2に渡す必要があると想定します。 routes.json
内の単一のルートpattern
正規表現をすべてテストすることもできますが、多くは類似しているため、代わりに、より短くて迅速なすべてのrouteAlias
エントリの一意のセットを取得するだけです。
Windows で開発する場合は、おそらく Unix インターフェイスを提供するプログラムを使用する必要があります。
これを行うには、いくつかのオプションがあります。
さらに、Node をインストールする必要があります。 WSL に Node をインストールする手順は次のとおりです。
私たちは現在、Scratch の既存の構造からこの Web クライアントへの移行過程にあります。移行に伴い、本番環境で適切に動作するために、このクライアントが既存のインフラストラクチャとどのように対話する必要があるかに関連するいくつかの問題が発生することになります。
これを Web クライアントとして使用するように移行することに加えて、Scratch は新しい API バックエンドである Scratch REST API (クローズドソース) の使用にも移行しています。これも現在開発中で未完成であるため、API エンドポイントが存在しない場合は既存の Scratch エンドポイントを使用するように設定されています。ここでFALLBACK
が登場します。
私たちが現在抱えている問題のほとんどは、 FALLBACK
の使用を中心に展開しています。この変数は、この Web クライアントのコンテキスト内でリクエストが失敗した場合、またはAPI_HOST
使用する場合にフォールバックする URL を指定するために使用されます。プロセス内で指定されていない場合は使用されず、Web クライアントまたは API 経由以外のリクエストは到達できなくなります。
FALLBACK=https://scratch.mit.edu
を設定すると、Web クライアントが開発環境の Scratch Web サイトからデータを取得できるようになります。ただし、セキュリティ上の懸念があるため、開発環境を通じて Scratch にデータを送信しようとしても機能しません。これは、当面の間、次のものが壊れることを意味します。
さらに、 FALLBACK=https://scratch.mit.edu
を設定した場合、まだ移行されていない Web サイトの部分 (現在はDiscuss
、 Profile
、 My Stuff
など) へのリンクをクリックすると、次のリンクが表示されることに注意してください。 Scratch Web サイト自体。