Skip to content

GitLab

S
scratch-www
Unverified Commit 16cd07ce authored by Benjamin Wheeler's avatar Benjamin Wheeler Committed by GitHub
Browse files
Options

Merge pull request #3568 from benjiwheeler/readme-refactor 

major reformat of README, with changes to indenting and testing instructions
parents f6de9721 9e38129f
Hide whitespace changes
Inline Side-by-side
Showing with 194 additions and 52 deletions
README.md
View file @ 16cd07ce
## scratch-www
# scratch-www
#### Standalone web client for Scratch
[![Build Status](https://travis-ci.org/LLK/scratch-www.svg)](https://travis-ci.org/LLK/scratch-www)
[![Coverage Status](https://coveralls.io/repos/github/LLK/scratch-www/badge.svg?branch=develop)](https://coveralls.io/github/LLK/scratch-www?branch=develop)
[![dependencies Status](https://david-dm.org/llk/scratch-www/status.svg)](https://david-dm.org/llk/scratch-www)
[![devDependencies Status](https://david-dm.org/llk/scratch-www/dev-status.svg)](https://david-dm.org/llk/scratch-www?type=dev) [![Greenkeeper badge](https://badges.greenkeeper.io/LLK/scratch-www.svg)](https://greenkeeper.io/)
[![Greenkeeper badge](https://badges.greenkeeper.io/LLK/scratch-www.svg)](https://greenkeeper.io/)
### Where am I?
Physically? No idea.
## Overview
Digitally? You’re at Scratch’s open source web client!
This is Scratch’s open source web client! This is the code for much of the [Scratch website](https://scratch.mit.edu).
We’re working to update the [Scratch website](https://scratch.mit.edu) to use a new codebase, contained in this repository.
In particular, this codebase includes code for:
* the "project page", which shows a playable version of the project, along with the project's title, description, comments, remixes and studios; this page operates in the background when you "See inside" a project
* the site's home page
* the Ideas page
* landing pages for various Scratch extensions, such as LEGO MINDSTORMS and micro:bit
* the info page for Scratch Desktop
* and other pages such as Credits and FAQ.
We’re currently building Scratch using [React](https://facebook.github.io/react/) and [SCSS](http://sass-lang.com/documentation/file.SASS_REFERENCE.html). Here are some resources to help you get acquainted with how we’re working on the Scratch codebase:
### How this fits in with other Scratch repos
The scratch-www project has lots of aspects of its design that are particular to our backend systems.
To use it for your own project, you would have to look at all the places it makes backend calls, and
create your own backend systems to perform those functions.
The [scratch-gui](https://github.com/LLK/scratch-gui) project, on the other hand, is designed to be
able to be used by anyone, without needing to create backend systems, though it also can support
backend systems for project and asset saving.
### Contributing
We welcome your contributions to this codebase! You may want to start by browsing [the current
list of open issues labeled "help wanted"](https://github.com/LLK/scratch-www/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).
Contributing to scratch-www can be more difficult than contributing to
[scratch-gui](https://github.com/LLK/scratch-gui). This is because scratch-gui can be run on its
own, without needing any other services to be running, while scratch-www needs to communicate
with several backend systems that the Scratch team runs (see "How this fits in with other Scratch
repos" above). If you are new to contributing to Scratch's source code, we suggest you start
by becoming familiar with scratch-gui and its [list of open issues labeled "help
wanted"](https://github.com/LLK/scratch-gui/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).
To contribute, please follow the [standard steps for contributing to a project on
GitHub](https://github.com/firstcontributions/first-contributions).
### License
See the [LICENSE](https://github.com/LLK/scratch-www/blob/master/LICENSE) file in this repo.
## Understanding this codebase
### Guides
Here are some resources to help you get acquainted with how we’re working on the Scratch codebase:
* [Style Guide](https://github.com/LLK/scratch-www/wiki/Style-Guide)
* [Testing Guide](https://github.com/LLK/scratch-www/wiki/Testing-Guide-for-Bugfixes)
* [Localization Guide](https://github.com/LLK/scratch-www/wiki/Localization-Guide)
* [Map of the repository](https://github.com/LLK/scratch-www/wiki/Repo-Map)
### Core technologies
Significant core technologies this codebase uses include:
#### Development technologies
* [Node](https://nodejs.org/)
* [Webpack](https://webpack.js.org/)
* [React](https://facebook.github.io/react/)
* [Redux](https://redux.js.org/)
* [Sass](http://sass-lang.com/documentation/file.SASS_REFERENCE.html)
#### Testing technologies
Our tests use:
* [Jest](https://jestjs.io/) (we are writing most new tests in Jest)
* [Tap](https://node-tap.org/) (we are moving away from using Tap, but many tests still use it)
* [Enzyme](https://airbnb.io/enzyme/)
* [Selenium](https://selenium.dev/)
## Developing scratch-www
### Before Getting Started
* Make sure you have node (v4.2 or higher) and npm [installed](https://docs.npmjs.com/getting-started/installing-node)
We use npm (Node Package Manager) to maintain and update packages required to build the site.
### Update Packages
It's important to make sure that all of the dependencies are up to date because the scratch-www code only works with specific versions of the dependencies. You can update the packages by running this command:
Make sure you have installed:
* [node](https://docs.npmjs.com/getting-started/installing-node): version 8 or higher
* npm (Node Package Manager): used to maintain and update packages required to build the site
```bash
npm install
```
### Update Packages
### To Build
To compile the source code into HTML and JavaScript bundles browsers can read, run this command:
It's important to make sure that all of the dependencies are up to date because the
scratch-www code only works with specific versions of the dependencies.
You can update the packages by using the command:
```bash
npm run build
npm install
```
If you want to run a server that rebuilds the files as you edit them, skip to the To Run section below.
#### Warnings during npm install
......@@ -52,34 +109,54 @@ npm WARN react-addons-test-utils@0.14.7 requires a peer of react@^0.14.7 but non
npm WARN react-dom@0.14.8 requires a peer of react@^0.14.8 but none was installed.
```
These currently exist in static/js/lib
These currently exist in static/js/lib .
### To Build
### To Run
If you would like to create a temporary version of the site on your machine that you can access through your web browser run the command below. Building (see To Build above) is not necessary for this step and the temporary server can be turned off (see To Stop below).
To compile the source code into HTML and JavaScript bundles browsers can read, you can create
a temporary version of the site on your machine that you can access through your web browser.
The intl directory must be built separately with the `npm run translate` line below in order for the text to appear properly.
You can either "build" the site a single time, by running:
```bash
npm run build
```
Or, you can run a server that rebuilds the files as you edit them, by running the commands:
```bash
npm run translate
npm start
```
The site hosted on your local machine can now be accessed by a web browser by entering localhost:8333 into your web browser.
*NOTE: `npm run translate` builds the intl directory. The site will build fine without it,
but translatable text strings will not show up correctly until you have built intl.*
During development, `npm start` watches any update you make to files in either
`./static` or `./src` and triggers a rebuild of the project. In development,
the build is stored in memory, and not served from the `./build` directory.
### Viewing the local site
During development, `npm start` watches any update you make to files in either `./static` or `./src` and triggers a rebuild of the project. In development, the build is stored in memory, and not served from the `./build` directory.
Once you have built the local site, using either `npm run build` or `npm start`,
the site hosted on your local machine can be accessed by a web browser by entering
`localhost:8333` into your browser's address bar.
### Troubleshooting
When running `npm start`, here are some important log messages to keep an eye out for:
* `webpack: bundle is now VALID.` – The bundle has been loaded into memory and is now viewable in the browser. This will show up both once `npm start` has completed its setup, and also once updates you make to files have been re-compiled for viewing in the browser.
* `webpack: bundle is now INVALID.` – If you see this, then it means you have made updates to files that are still being compiled for browser viewing. Pages will still be viewable, but they will not see any updates you made yet.
Once running, open `http://localhost:8333` in your browser. If you wish to have the server reload automatically, you can install either [nodemon](https://github.com/remy/nodemon) or [forever](https://github.com/foreverjs/forever).
### To stop npm
### To stop
To stop the process that is making the site available to your web browser (created above in To Start) use `^C`.
To stop the `npm start` process which is making the site available to your web browser
(created above in "To Build"), use `^C` (control-c) in the terminal.
#### Configuration
`npm start` can be configured with the following environment variables
`npm start` can be configured with the following environment variables, by setting them in
the beginning of the command, before `npm start`:
| Variable | Default | Description |
| --------------- | ---------------------------------- | ---------------------------------------------- |
......@@ -93,33 +170,87 @@ To stop the process that is making the site available to your web browser (creat
| `NODE_ENV` | `null` | If not `production`, app acts like development |
| `PORT` | `8333` | Port for devserver (http://localhost:XXXX) |
**NOTE:** Because by default `API_HOST=https://api.scratch.mit.edu`, please be aware that, by default, you will be seeing and interacting with real data on the Scratch website.
*NOTE: Because by default `API_HOST=https://api.scratch.mit.edu`, please be aware that, by default, you will be seeing and interacting with real data on the Scratch website.*
## Tests
### Unit tests
Most of our unit tests run using Jest, but older unit tests use the TAP framework.
#### Run all tests
To build the application and run all unit and localization tests, use the command:
### Unit Tests
To run:
```bash
npm test
```
This will build the application and run the unit and localization tests. Some of the tests are run using the TAP framework and others run using Jest.
#### Run one test
To run a single unit test file from the command-line using Jest, use the command:
```bash
node_modules/.bin/jest ./test/unit/PATH/TO/FILENAME.test.js
```
*NOTE: replace `PATH/TO/FILENAME` with the actual path to the file you wish to run.*
### Integration tests
We are transitioning from using TAP to using Jest as our testing framework so for the time being our tests run using both.
#### Running the tests
Our integration tests assume that a larger environment is running than just scratch-www
on its own; for instance, many require that a test user be able to log in to the site,
which requires backend and database support.
By default, tests run against our Staging instance, but you can pass in a different
location with the ROOT_URL environment variable (see below) if you want to run the
tests against another location--for instance, your local build.
* By default, tests run against our Staging instance, but you can pass in a different location with the ROOT_URL environment variable (see below) if you want to run the tests against e.g. your local build
We are transitioning from using TAP to using Jest as our testing framework,
so for the time being our tests run using both.
#### Running the tests
* Run all tests from the command-line: `$ SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu npm run test:integration`
* To run a single file from the command-line using TAP: `$ SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu node_modules/.bin/tap ./test/integration-legacy/smoke-testing/filename.js --timeout=3600`
* The timeout var is for the length of the entire tap test-suite; if you are getting a timeout error, you may need to adjust this value (some of the Selenium tests take a while to run)
* To run a single file from the command-line using Jest: `$ SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu node_modules/.bin/jest ./test/integration/filename.test.js`
To run all integration tests from the command-line:
```bash
SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu npm run test:integration
```
To run a single file from the command-line using Jest:
```bash
SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu node_modules/.bin/jest ./test/integration/filename.test.js
```
To run a single file from the command-line using TAP:
```bash
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
```
* the `-R classic` makes tap use the old reporting style, which avoids an error with the "nyc" package
* `--no-coverage` is because we do not use the coverage-tracking feature of tap
* the `timeout` argument is for the length of the entire tap test-suite; if you are getting a timeout error, you may need to adjust this value (some of the Selenium tests take a while to run)
#### Running Remote tests
* TAP tests can be run using Saucelabs, an online service that can test browser/os combinations remotely. Currently all tests are written for use for chrome on mac.
* You will need a Saucelabs account in order to use it for testing. To find the Access Key, click your username and select User Settings from the dropdown menu. Near the bottom of the page is your access key that you can copy and use in the command line.
* Currently Jest tests will not run with Saucelabs.
* To run tests using saucelabs run this command `$ SMOKE_USERNAME=username SMOKE_PASSWORD=password SAUCE_USERNAME=saucelabsUsername SAUCE_ACCESS_KEY=saucelabsAccessKey ROOT_URL=https://scratch.mit.edu npm run test:integration:remote`
Integration tests can be run using Saucelabs, an online service that can test multiple
browser/OS combinations remotely. (Currently, all tests are written for use for Chrome on Mac).
You will need a Saucelabs account in order to use it for testing. If you have one, you can
find your Access Key:
1. click your username
1. select "User Settings" from the dropdown menu
1. near the bottom of the page is your access key
To run tests using Saucelabs, run the command:
```bash
SMOKE_USERNAME=username SMOKE_PASSWORD=password SAUCE_USERNAME=saucelabsUsername SAUCE_ACCESS_KEY=saucelabsAccessKey ROOT_URL=https://scratch.mit.edu npm run test:integration:remote
```
*NOTE: Currently Jest tests will not run with Saucelabs.*
#### Configuration
......@@ -133,7 +264,7 @@ We are transitioning from using TAP to using Jest as our testing framework so fo
| `SAUCE_USERNAME` | `None` | Username for your Sauce Labs account |
| `SAUCE_ACCESS_KEY` | `None` | Access Key for Sauce Labs found under User Settings |
### To Deploy
## To Deploy
Deploying to staging or production will upload code to S3 and configure Fastly.
......@@ -154,20 +285,31 @@ npm run build && npm run deploy
| `AWS_SECRET_ACCESS_KEY` | `''` | AWS secret access key for S3 |
| `S3_BUCKET_NAME` | `''` | S3 bucket name to deploy into |
## Windows
For development on Windows, you will probably need to use a program that provides you a Unix interface.
There are several options for doing this:
* Use the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) to run Linux inside Windows
* Use [Cygwin](https://www.cygwin.com/)
* Use Wubi, a Windows Installer for Ubuntu that allows you to have Ubuntu and Windows on one disk, without the need of an extra partition. There is a [version for Windows XP, Vista, or 7](https://wiki.ubuntu.com/WubiGuide) and a [version for Windows 8 or higher](https://github.com/hakuna-m/wubiuefi).
In addition, you will need to install Node; [here are instructions for installing Node on WSL](https://docs.microsoft.com/en-us/windows/nodejs/setup-on-wsl2#install-nvm-nodejs-and-npm).
## Current issues with developing scratch-www
### Current issues with the development
We're currently in the process of transitioning into this web client from Scratch's existing structure. As we transition, there are going to be some issues along the way that relate to how this client needs to interact with the existing infrastructure to work properly in production.
#### FALLBACK
On top of migrating to using this as our web client, Scratch is also transitioning into using a new API backend, Scratch REST API. As that is also currently in development and incomplete, we are set up to fall back to using existing Scratch endpoints if an API endpoint does not exist – which is where the `FALLBACK` comes in.
### FALLBACK
On top of migrating to using this as our web client, Scratch is also transitioning into using a new API backend, Scratch REST API (closed-source). As that is also currently in development and incomplete, we are set up to fall back to using existing Scratch endpoints if an API endpoint does not exist – which is where the `FALLBACK` comes in.
Most of the issues we have currently revolve around the use of `FALLBACK`. This variable is used to specify what URL to fall back onto should a request fail within the context of this web client, or when using the `API_HOST`. If not specified in the process, it will not be used, and any request that is not made through the web client or the API will be unreachable.
Setting `FALLBACK=https://scratch.mit.edu` allows the web client to retrieve data from the Scratch website in your development environment. However, because of security concerns, trying to send data to Scratch through your development environment won't work. This means the following things will be broken for the time being:
* Login on the splash page (*In the process of being fixed*)
* Some update attempts to production data made through a development version of the web client
Additionally, if you set `FALLBACK=https://scratch.mit.edu`, be aware that clicking on links to parts of the website not yet migrated over (currently such as `Explore`, `Discuss`, `Profile`, etc.) will take you to the Scratch website itself.
#### Windows
Some users have experienced difficulties when trying to get our web client to work on Windows. One solution could be to use [Cygwin](https://www.cygwin.com/). If that doesn't work, you might want to use [Wubi](https://wiki.ubuntu.com/WubiGuide) (Windows XP, Vista, 7) or [Wubiuefi](https://github.com/hakuna-m/wubiuefi) (Windows 8 or higher). Wubi(uefi) is a Windows Installer for Ubuntu that allows you to have Ubuntu and Windows on one disk, without the need of an extra partition.
Additionally, if you set `FALLBACK=https://scratch.mit.edu`, be aware that clicking on links to parts of the website not yet migrated over (currently such as `Discuss`, `Profile`, `My Stuff`, etc.) will take you to the Scratch website itself.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment