Skip to content
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.

Sign up for GitHub

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

Updating Dev.md for better readability #381

Open
wants to merge 6 commits into
base: develop
Choose a base branch
from
Open

Updating Dev.md for better readability #381

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7a6c033
Update DEV.md
SamarthBagga Jan 11, 2024
6b1dc99
Update DEV.md
SamarthBagga Jan 11, 2024
2e9c810
Update DEV.md
SamarthBagga Jan 11, 2024
64e4b73
Update DEV.md
SamarthBagga Jan 11, 2024
5804d37
Update DEV.md
SamarthBagga Jan 11, 2024
c719970
Update DEV.md
SamarthBagga Jan 21, 2024
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
145 changes: 72 additions & 73 deletions docs/DEV.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Developer Guide

## Setup Development Environment
## Setup the Development Environment

### Without Docker
### 1. Without Docker

This is a _**TypeScript**_ project that uses _**React**_. You'll just need
_[**Node.js**](https://nodejs.org/en) v16_ and _**npm**_ installed on your development machine.
_[**Node.js**](https://nodejs.org/en) v16_ or higher and _**npm**_ installed on your development machine.
Copy link
Member

Choose a reason for hiding this comment

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

We should confirm this assertion.

Copy link
Author

Choose a reason for hiding this comment

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

@walterbender, I have tested it on v18 and v20 and it works fine on both.

Although, this is sufficient to run, build, and test the project as a whole, you might need some
extra tools for other development tasks.

Expand All @@ -14,7 +14,7 @@ _**ts-node**_ (_Node.js executable for TypeScript_) to manually execute `.ts` sc
you'll need an _HTTP_ server like _**http-server**_ (_a HTTP server program_), if you want to serve
files manually.

Once _**npm**_ is installed, to install the above, run
1. After setting up npm, install the above with:

```bash
npm i -g http-server
Expand All @@ -24,13 +24,13 @@ npm i -g ts-node

_**Note:**_ Users on _Linux_ and _MacOS_ are required to add a `sudo` before these commands.

Check installation using
2. Verify the installation with:

```bash
node -v && npm -v && tsc -v && ts-node -v && http-server -v
```

Output should look like
Output should look like:

```bash
v16.14.0
Expand All @@ -40,13 +40,19 @@ v10.6.0
v14.1.0
```

### With Docker
3. Clone the repo using:

```bash
git clone https://github.com/sugarlabs/musicblocks-v4.git
```

### 2. With Docker

This project development tools have been containerized using [**docker**](https://www.docker.com/).
Therefore, to use an execution sandbox, it requires **docker** to be installed on the development
machine.

1. Setup _docker_.
1. Setup _docker_:

- For _Linux_, [install _Docker Engine_](https://docs.docker.com/engine/install/). You'll also
need to [install _Docker Compose_](https://docs.docker.com/compose/install/).
Expand All @@ -55,8 +61,8 @@ machine.

2. Open a terminal and navigate to working directory (where the source code will reside).

3. _Git Clone_ (additional [installation](https://git-scm.com/downloads) of _Git_ required on
Windows) this repository using
3. _Clone_ (additional [installation](https://git-scm.com/downloads) of _Git_ required on
Windows) this repository using:

```bash
git clone https://github.com/sugarlabs/musicblocks-v4.git
Expand All @@ -68,19 +74,19 @@ Windows) this repository using
[built initial development image](https://github.com/sugarlabs/musicblocks-v4/pkgs/container/musicblocks/16217005?tag=4-dev)
has been published to
[_Sugar Labs GitHub Container Registry_ (_GHCR_)](https://github.com/orgs/sugarlabs/packages?ecosystem=container),
which can be pulled directly, so you don't have to build it again. Pull using
which can be pulled directly, so you don't have to build it again. Pull using:

```bash
docker pull ghcr.io/sugarlabs/musicblocks:4-dev
```

Nagivate inside the project directory and launch the _docker network_ using
Nagivate inside the project directory and launch the _docker network_ using:

```bash
docker-compose up -d
```

or (for _Docker v1.28_ and above)
or (for _Docker v1.28_ and above):

```bash
docker compose up -d
Expand All @@ -91,7 +97,7 @@ Windows) this repository using
locally, it'll not be rebuilt. To force a rebuild from the `Dockerfile` before launching the
_docker network_, add the `--build` flag.

5. In a second terminal, run
5. In a second terminal, run:

```bash
docker attach musicblocks-4-dev
Expand All @@ -102,13 +108,13 @@ Windows) this repository using

6. _**Node.js**_ (_Node.js Runtime_), _**npm**_ (_Node.js Package Manager_), _**tsc**_ (_TypeScript
Compiler_), _**ts-node**_ (_Node.js executable for TypeScript_), and _**http-server**_ (_a HTTP
server program_) should be installed. Check using
server program_) should be installed. Check using:

```bash
node -v && npm -v && tsc -v && ts-node -v && http-server -v
```

Output should look like
Output should look like this:

```bash
v16.14.0
Expand All @@ -118,7 +124,7 @@ Windows) this repository using
v14.1.0
```

7. To shut down the _docker network_, run (in the terminal where you ran `docker-compose up -d` or
7. To shut down the _docker network_, run (in the same terminal where you ran `docker-compose up -d` or
`docker compose up -d`)

```bash
Expand All @@ -130,112 +136,112 @@ Windows) this repository using
```bash
docker compose down
```

## Commands
## Personal Access Token (PAT)

**Note: This repository uses `sugarlabs/musicblocks-v4-lib` as an _npm_ package which is published to
the _GitHub npm Registry_ of Sugar Labs. Before you install the dependencies you need to make sure that
your _GitHub Personal Access Token_ (_PAT_) is stored in your local system's _npm_ configuration file
`.npmrc`.**

**Note: Be sure to request permission for ```read: packages```**

Learn
[how to create a _PAT_](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-token).

Add your _PAT_ to `.npmrc` using
**Note: Ensure to mark the checkbox labeled ```read: packages```**

Add your _PAT_ to `.npmrc` using:

```bash
echo "//npm.pkg.github.com/:_authToken=[YOUR_GITHUB_PERSONAL_ACCESS_TOKEN]" >> ~/.npmrc
```
## Run a development server and test suites



After you are set-up, the steps you take depend on what you want to do:

- **Run a development server and test suites**

1. To install all the dependencies (in `package.json`), run

```bash
npm ci
```
1. To install the dependencies (in `package.json`), run:

2. Run _React scripts_.
```bash
npm ci
```

- For unoptimized development serving, run
2. Run _React scripts_.

```bash
npm run serve
```
- For unoptimized development serving, run:

Visit `localhost:5173` in a browser to view the web page served.
```bash
npm run serve
```

- For generating a generic production build, run
Visit `localhost:5173` in a browser to view the web page served.

```bash
npm run build
```
- For generating a generic production build, run:

- For generating a production build under the subdirectory `/musicblocks-v4/`, run
```bash
npm run build
```

```bash
npm run build:gh
```
- For generating a production build under the subdirectory `/musicblocks-v4/`, run:

- For serving the last production build (`dist` folder), run
```bash
npm run build:gh
```

- For serving the last production build (`dist` folder), run:

```bash
npm run preview
```
```bash
npm run preview
```

Visit `localhost:4173` in a browser to view the web page served.
Visit `localhost:4173` in a browser to view the web page served.

- For running unit tests, run
- For running unit tests, run:

```bash
npm run test:unit
```
```bash
npm run test:unit
```

- For running E2E tests, run
- For running E2E tests, run:

```bash
## In 1 terminal
npm run build
npm run preview
## In another terminal
npm run test:e2e
```
```bash
## In 1 terminal
npm run build
npm run preview
## In another terminal
npm run test:e2e
```

_**Note:**_ If you're running using _Docker Desktop_ on _Windows_ or _Mac_, you might experience
longer execution times for these scripts. This happens due to cross-file-system communication.
Duration varies across machines; duration primarily depends on hard drive read/write speed.
_**Note:**_ If you're running using _Docker Desktop_ on _Windows_ or _Mac_, you might experience longer execution times for these scripts. This happens due to cross-file-system communication. Duration varies across machines; duration primarily depends on hard drive read/write speed.

- **Miscellaneous commands**
## Miscellaneous commands

_**Note:**_ This requires _**Node.js**_ (_Node.js Runtime_), _**tsc**_ (_TypeScript Compiler_), and
_**ts-node**_ (_Node.js executable for TypeScript_) to be installed. If you are using _Docker_, they'll
be pre-installed in the container.

- To launch the _Node.js runtime_, run
- To launch the _Node.js runtime_, run:

```bash
node
```

- To run a _JavaScript_ file, say `file.js`, run
- To run a _JavaScript_ file, say `file.js`, run:

```bash
node file.js
```

- To transpile a _TypeScipt_ file, say `file.ts`, to _JavaScript_, run
- To transpile a _TypeScipt_ file, say `file.ts`, to _JavaScript_, run:

```bash
tsc file.ts
```

This transpilation produces `file.js`.

- To run a _TypeScript_ file directly, say `file.ts`, run
- To run a _TypeScript_ file directly, say `file.ts`, run:

```bash
ts-node file.ts
Expand All @@ -258,10 +264,3 @@ _keyboard shortcuts_, etc.
_**Visual Studio Code**_ (_**VSCode**_) is currently the most-popular code editor for reasons like
being _lightweight_, _cleaner_, large marketplace of _extensions_, integrated _source control_
features, _debugger_, _remote explorer_ support, _regular expression_ based find/replace, etc.

Copy link
Member

Choose a reason for hiding this comment

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

Any reason you deleted this section?

Copy link
Author

Choose a reason for hiding this comment

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

@walterbender, I accidentally removed it, i have now reverted the change.

In fact, a workspace configuration file for _vscode_`.vscode/settings.json` has already been added.
Recommended extensions for this project are `Babel JavaScript`, `Docker`, `ESLint`, `Git Graph`,
`GitLens`, `markdownlint`, `Prettier`, `SCSS IntelliSense`, and `SVG`.

All that, however, shouldn't necessarily stop you from using _**Emacs**_, _**Nano**_, or _**Vim**_,
if that's your poison :D. Happy coding!