Skip to content

Bump Node.js to version 20, update documentation #2712

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Jan 15, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 62 additions & 73 deletions .github/workflows/build-development.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,76 +9,65 @@ jobs:
name: Build and deploy sourceacademy.org
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- name: Use Node.js
uses: actions/setup-node@v2-beta
with:
node-version: '16'
- name: Setup Sentry CLI
run: |
curl -sL https://sentry.io/get-cli/ | INSTALL_DIR=. bash
- name: Get yarn cache directory path
id: yarn-cache-dir-path
run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
- id: get-time
run: echo "time=$(date -Iseconds)" >> $GITHUB_OUTPUT
- uses: actions/cache@v2
id: yarn-cache
with:
path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
key: 1-${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
1-${{ runner.os }}-yarn-
- uses: actions/cache@v2
id: build-cache
with:
path: node_modules/.cache
key: 1-${{ runner.os }}-build-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
1-${{ runner.os }}-build-
- name: yarn install and build
run: |
yarn install
yarn run build
env:
REACT_APP_URL_SHORTENER_SIGNATURE: ${{ secrets.REACT_APP_URL_SHORTENER_SIGNATURE }}
REACT_APP_URL_SHORTENER_BASE: ${{ secrets.REACT_APP_URL_SHORTENER_BASE }}
REACT_APP_SENTRY_DSN: ${{ secrets.REACT_APP_SENTRY_DSN }}
REACT_APP_GOOGLE_CLIENT_ID: ${{ secrets.REACT_APP_GOOGLE_CLIENT_ID }}
REACT_APP_GOOGLE_API_KEY: ${{ secrets.REACT_APP_GOOGLE_API_KEY }}
REACT_APP_GOOGLE_APP_ID: ${{ secrets.REACT_APP_GOOGLE_APP_ID }}
REACT_APP_PLAYGROUND_ONLY: "TRUE"
REACT_APP_ENABLE_GITHUB_ASSESSMENTS: "TRUE"
REACT_APP_VERSION: ${{ format('{0}-{1}', github.sha, steps.get-time.outputs.time) }}
REACT_APP_ENVIRONMENT: "pages"
REACT_APP_MODULE_BACKEND_URL: https://source-academy.github.io/modules
REACT_APP_SHAREDB_BACKEND_URL: ${{ secrets.REACT_APP_SHAREDB_BACKEND_URL }}
PUBLIC_URL: "https://sourceacademy.org"
REACT_APP_GITHUB_OAUTH_PROXY_URL: ${{ secrets.REACT_APP_GITHUB_OAUTH_PROXY_URL }}
REACT_APP_GITHUB_CLIENT_ID: ${{ secrets.REACT_APP_GITHUB_CLIENT_ID }}
- name: Create Sentry release
working-directory: build
run: |
SENTRY_RELEASE="cadet-frontend@$REACT_APP_VERSION"
"$GITHUB_WORKSPACE/sentry-cli" releases new -p "$SENTRY_PROJECT" "$SENTRY_RELEASE"
"$GITHUB_WORKSPACE/sentry-cli" releases set-commits --auto "$SENTRY_RELEASE"
"$GITHUB_WORKSPACE/sentry-cli" releases files "$SENTRY_RELEASE" upload-sourcemaps --url-prefix '~/static/js' --rewrite static/js
"$GITHUB_WORKSPACE/sentry-cli" releases finalize "$SENTRY_RELEASE"
"$GITHUB_WORKSPACE/sentry-cli" releases deploys "$SENTRY_RELEASE" new -e pages
env:
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
SENTRY_ORG: sourceacademy
SENTRY_PROJECT: cadet-frontend
REACT_APP_VERSION: ${{ format('{0}-{1}', github.sha, steps.get-time.outputs.time) }}
- name: Remove sourcemaps
working-directory: build
run: |
find -name '*.map' -print -delete
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
external_repository: source-academy/sourceacademy.org
deploy_key: ${{ secrets.DEPLOY_PRIVATE_KEY }}
publish_dir: ./build
publish_branch: master
force_orphan: true
- name: Checkout repository
uses: actions/checkout@v4
- name: Install dependencies (apt)
run: |
sudo apt-get install -y --no-install-recommends \
libxi-dev libgl1-mesa-dev
- name: Setup node
uses: actions/setup-node@v4
with:
node-version: 20
cache: yarn
- name: Setup Sentry CLI
run: |
curl -sL https://sentry.io/get-cli/ | INSTALL_DIR=. bash
- id: get-time
run: echo "time=$(date -Iseconds)" >> $GITHUB_OUTPUT
- name: yarn install and build
run: |
yarn install --frozen-lockfile
yarn run build
Comment on lines +28 to +31
Copy link
Contributor

@chownces chownces Jan 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is there a reason for removing the build cache here?

looks good otherwise (M2 MBA Sonoma, Node 20.9.0, Python 3.9)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using

with:
  cache: yarn

in actions/setup-node handles this caching for us. We no longer need to manually set up caching of certain files/folders anymore.

env:
REACT_APP_URL_SHORTENER_SIGNATURE: ${{ secrets.REACT_APP_URL_SHORTENER_SIGNATURE }}
REACT_APP_URL_SHORTENER_BASE: ${{ secrets.REACT_APP_URL_SHORTENER_BASE }}
REACT_APP_SENTRY_DSN: ${{ secrets.REACT_APP_SENTRY_DSN }}
REACT_APP_GOOGLE_CLIENT_ID: ${{ secrets.REACT_APP_GOOGLE_CLIENT_ID }}
REACT_APP_GOOGLE_API_KEY: ${{ secrets.REACT_APP_GOOGLE_API_KEY }}
REACT_APP_GOOGLE_APP_ID: ${{ secrets.REACT_APP_GOOGLE_APP_ID }}
REACT_APP_PLAYGROUND_ONLY: 'TRUE'
REACT_APP_ENABLE_GITHUB_ASSESSMENTS: 'TRUE'
REACT_APP_VERSION: ${{ format('{0}-{1}', github.sha, steps.get-time.outputs.time) }}
REACT_APP_ENVIRONMENT: 'pages'
REACT_APP_MODULE_BACKEND_URL: https://source-academy.github.io/modules
REACT_APP_SHAREDB_BACKEND_URL: ${{ secrets.REACT_APP_SHAREDB_BACKEND_URL }}
PUBLIC_URL: 'https://sourceacademy.org'
REACT_APP_GITHUB_OAUTH_PROXY_URL: ${{ secrets.REACT_APP_GITHUB_OAUTH_PROXY_URL }}
REACT_APP_GITHUB_CLIENT_ID: ${{ secrets.REACT_APP_GITHUB_CLIENT_ID }}
- name: Create Sentry release
working-directory: build
run: |
SENTRY_RELEASE="cadet-frontend@$REACT_APP_VERSION"
"$GITHUB_WORKSPACE/sentry-cli" releases new -p "$SENTRY_PROJECT" "$SENTRY_RELEASE"
"$GITHUB_WORKSPACE/sentry-cli" releases set-commits --auto "$SENTRY_RELEASE"
"$GITHUB_WORKSPACE/sentry-cli" releases files "$SENTRY_RELEASE" upload-sourcemaps --url-prefix '~/static/js' --rewrite static/js
"$GITHUB_WORKSPACE/sentry-cli" releases finalize "$SENTRY_RELEASE"
"$GITHUB_WORKSPACE/sentry-cli" releases deploys "$SENTRY_RELEASE" new -e pages
env:
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
SENTRY_ORG: sourceacademy
SENTRY_PROJECT: cadet-frontend
REACT_APP_VERSION: ${{ format('{0}-{1}', github.sha, steps.get-time.outputs.time) }}
- name: Remove sourcemaps
working-directory: build
run: |
find -name '*.map' -print -delete
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
external_repository: source-academy/sourceacademy.org
deploy_key: ${{ secrets.DEPLOY_PRIVATE_KEY }}
publish_dir: ./build
publish_branch: master
force_orphan: true
10 changes: 7 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,15 @@ jobs:
commands: [tsc, 'format:ci', eslint, build, test, test-coveralls]
steps:
- name: Checkout repository
uses: actions/checkout@v3
uses: actions/checkout@v4
- name: Install dependencies (apt)
run: |
sudo apt-get install -y --no-install-recommends \
libxi-dev libgl1-mesa-dev
- name: Setup node
uses: actions/setup-node@v3
uses: actions/setup-node@v4
with:
node-version: 16
node-version: 20
cache: yarn
- name: Install dependencies
run: yarn install --frozen-lockfile
Expand Down
1 change: 1 addition & 0 deletions .node-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
20.9.0
40 changes: 40 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Contributing Guide

Refer to our issue tracker and contribute to any open issues you are able to spot there. If you have any new issues, please do post there as well. We welcome any form of contribution and are open to any new ideas you may have for the project!

To start contributing, create a fork from our repo and send a PR. Refer to [this article](https://help.github.com/en/articles/fork-a-repo) for more information.

## Application Structure

1. `assets` contains static assets.
1. `commons` contains components or other code common to more than one page.
1. `features` contains action creators, reducers and type declarations for specific functions.
1. `pages` contains pages and components used only in one page; its layout should mirror the actual routes.
1. `styles` contains all SCSS styles.

## Testing

The frontend comes with an extensive test suite. To run the tests after you made your modifications, run
`yarn test`. Regression tests are run automatically when you want to push changes to this repository.
The regression tests are generated using `jest` and stored as snapshots in `src/\_\_tests\_\_`. After modifying the frontend, carefully inspect any failing regression tests reported in red in the command line. If you are convinced that the regression tests and not your changes are at fault, you can update the regression tests by running:

```bash
yarn test --updateSnapshot
```

## Manually testing the frontend

Before pushing to Github, ensure that your code is formatted and your tests are passing. These two commands should help with that:

- `yarn run format` : formats your code
- `yarn run test`: runs the tests and prints the output

## Running your own js-slang

See [js-slang README](https://github.com/source-academy/js-slang#using-your-js-slang-in-local-source-academy) for instructions how to run your own js-slang in the frontend.

## TypeScript Coding Conventions

We reference [this guide](https://github.com/piotrwitek/react-redux-typescript-guide).

See also the [this standard in the wiki](https://github.com/source-academy/frontend/wiki/Coding-Standard).
79 changes: 19 additions & 60 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,29 +18,34 @@ The Source Academy (<https://sourceacademy.org/>) is an immersive online experie

## Getting Started

### Installation of Source Academy (latest version [available in GitHub Pages](https://source-academy.github.io/))
### Installation of [Source Academy](https://source-academy.github.io/)

1. Install the current LTS version of Node.js. The current version (usually the version one greater than the current LTS) may also work, but if you encounter issues, use the current or lower LTS version. (Known working version of node: v16.16.0)
2. Clone this repository and navigate to it using "cd" in your command line or shell tool.
3. Run `yarn install` to install dependencies.
- If you are on Ubuntu and encounter the error message: `No such file or directory: 'install'`, you might be running the incorrect "yarn" from the cmdtest testing suite instead of the JavaScript package manager of the same name. Refer to this [StackOverflow post](https://stackoverflow.com/questions/46013544/yarn-install-command-error-no-such-file-or-directory-install).
- If you are on the new M1 or M2 Mac chips, and encounter an error while installing `canvas`, refer to [this documentation](https://github.com/Automattic/node-canvas/wiki/Installation:-Mac-OS-X#homebrew) to install the requisite dependencies first.
1. Install the version of Node.js as specified in the `.node-version` file

1. Install Python (known working versions: `2.7`, `3.8`, `3.9`, `3.10`) – **Note: Python `3.11` does not work**

4. Run `yarn run start` to start the server at `localhost:8000`. **It might take a couple of minutes for the server to start.**
5. Point your browser to `http://localhost:8000` to see your local Source Academy.
1. Clone this repository and navigate to it using your command line

1. Run `yarn install` to install dependencies.

- If you are on Ubuntu and encounter the error message: `No such file or directory: 'install'`, you might be running the incorrect "yarn" from the cmdtest testing suite instead of the JavaScript package manager of the same name. Refer to this [StackOverflow post](https://stackoverflow.com/questions/46013544/yarn-install-command-error-no-such-file-or-directory-install).
- If you are on the new M1 or M2 Mac chips, and encounter an error while installing `canvas`, refer to [this documentation](https://github.com/Automattic/node-canvas/wiki/Installation:-Mac-OS-X#homebrew) to install the requisite dependencies first.

1. Run `yarn run start` to start the server at `localhost:8000`. **It might take a couple of minutes for the server to start.**

1. Point your browser to `http://localhost:8000` to see your local Source Academy.

In this edition, you will only see the Playground with all its tools, but no login options or homework submission features.

If you wish to set up the GitHub or Google Drive integrations, copy the `.env.example` file as `.env` and refer to [_Setting up your environment_](#setting-up-your-environment) below for the relevant configuration options.

### Installation of Source Academy @ NUS (access [latest production version here](https://sourceacademy.nus.edu.sg))
### Installation of [Source Academy @ NUS](https://sourceacademy.nus.edu.sg)

1. Repeat steps 1-4 above
1. Copy the `.env.example` file as `.env` and set the necessary variables (refer below for more information)
1. Run `yarn run start` to start the server at `localhost:8000`

1. Install the current LTS version of Node.js. The current version (usually the version one greater than the current LTS) may also work, but if you encounter issues, use the current LTS.
2. Clone this repository and navigate to it using "cd" in your command line or shell tool.
3. Run `yarn install` to install dependencies.
4. Copy the `.env.example` file as `.env` and set the necessary variables (refer below for more information)
5. Run `yarn run start` to start the server at `localhost:8000`. **It might take a couple of minutes for the server to start.**
**Note: It might take a couple of minutes for the server to start the first time.**

### Setting up your environment

Expand Down Expand Up @@ -88,39 +93,6 @@ See [here](https://github.com/source-academy/frontend/wiki/Google-Drive-Persiste
1. `REACT_APP_ENABLE_GITHUB_ASSESSMENTS`: Whether to enable the GitHub Assessments feature. Off by default.
1. `REACT_APP_SHOW_RESEARCH_PROMPT`: Whether to show the educational research consent prompt to users. This is mainly for instructors using their own deployment of Source Academy @ NUS to disable this prompt.

## Development

### Running the tests

Before pushing to Github, ensure that your code is formatted and your tests are passing. These two commands should help with that:

- `yarn run format` : formats your code
- `yarn run test`: runs the tests and prints the output

### Running your own js-slang

See [js-slang README](https://github.com/source-academy/js-slang#using-your-js-slang-in-local-source-academy) for instructions how to run your own js-slang in the frontend.

### Contribution Guidelines

Refer to our issue tracker and contribute to any open issues you are able to spot there. If you have any new issues, please do post there as well. We welcome any form of contribution and are open to any new ideas you may have for the project!

To start contributing, create a fork from our repo and send a PR. Refer to [this article](https://help.github.com/en/articles/fork-a-repo) for more information.

### Application Structure

1. `assets` contains static assets.
1. `commons` contains components or other code common to more than one page.
1. `features` contains action creators, reducers and type declarations for specific functions.
1. `pages` contains pages and components used only in one page; its layout should mirror the actual routes.
1. `styles` contains all SCSS styles.

### TypeScript Coding Conventions

We reference [this guide](https://github.com/piotrwitek/react-redux-typescript-guide).

See also the [this standard in the wiki](https://github.com/source-academy/frontend/wiki/Coding-Standard).

## Projects

For more info on specific frontend projects, please consult [our wiki](https://github.com/source-academy/frontend/wiki).
Expand All @@ -136,19 +108,6 @@ There are a few additional environment variables that are used when building and
1. `REACT_APP_CADET_LOGGER`: Log server URL. To test with cadet-logger on localhost, set it to `http://localhost:8001/assessment-logger`.
1. `REACT_APP_CADET_LOGGER_INTERVAL`: The interval (in ms) that the frontend should upload logs.

## Testing

The frontend comes with an extensive test suite. To run the tests after you made your modifications, run
`yarn test`. Regression tests are run automatically when you want to push changes to this repository.
The regression tests are generated using `jest` and stored as snapshots in `src/\_\_tests\_\_`. After modifying the frontend, carefully inspect any failing regression tests reported in red in the command line. If you are convinced that the regression tests and not your changes are at fault, you can update the regression tests by running:

``` {.}
$ yarn test --updateSnapshot
```

and then typing `a` to update all snapshots.
(if you run this on a macBook with ARM chip, you may run into errors; try to do this on a computer with x86 chip instead)

## License

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
Expand Down
3 changes: 3 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,9 @@
"url": "^0.11.1",
"webpack-bundle-analyzer": "^4.9.0"
},
"resolutions": {
"**/gl": "^6.0.2"
},
"browserslist": {
"production": [
"Firefox ESR",
Expand Down
Loading