Repository: NationalCentreTruthReconciliation/Secure-Record-Transfer
Pull request #519: Add Required Tools Section to DEVELOPERS.md
Author: login: yenaing-oo
Created: 2025-04-15T18:46:46Z | Merged: 2025-04-24T16:19:27Z

Closes https://github.com/NationalCentreTruthReconciliation/Secure-Record-Transfer/issues/515


Diff:
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 000000000..605927e33
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,8 @@
+{
+    "recommendations": [
+      "ms-python.python",
+      "charliermarsh.ruff",
+      "dbaeumer.vscode-eslint",
+      "tamasfe.even-better-toml",
+    ]
+  }
\ No newline at end of file
diff --git a/DEVELOPERS.md b/DEVELOPERS.md
index 8667cdb77..59124a76c 100644
--- a/DEVELOPERS.md
+++ b/DEVELOPERS.md
@@ -1,27 +1,102 @@
 # For Developers
 
-The developer documentation here assumes you are using [VSCode](https://code.visualstudio.com/).
+This page contains information relevant to developers working on this application.
 
 ## Supported Operating Systems
 
 This application is primarily designed for UNIX-based operating systems (Linux, macOS). Some functionality may not work correctly on Windows.
 
-If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility. You can install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) and then develop within that Linux environment.
+If you're developing on Windows, we strongly recommend using Windows Subsystem for Linux (WSL) to ensure compatibility.
+
+## Setting up Your Development Environment
+
+This section outlines the tools you need to install and the steps you need to take to prepare your machine for development.
+
+### All Platforms
+
+These instructions apply to all operating systems. First, install the following tools:
+
+- **VSCode** is our recommended IDE for development ([Download VSCode](https://code.visualstudio.com/)).
+- **Docker Desktop** or **Podman Desktop** is needed to run the containerized development environment ([Install Docker Desktop](https://docs.docker.com/get-docker/)) / ([Install Podman Desktop](https://podman.io/getting-started/installation)).
+  - If you have no preference over either tool, use Docker.
+
+### Mac/Linux-Specific Instructions
+
+If developing on Mac or Linux, you'll need the following tools:
+
+1. **Python 3.9+** ([Download Python](https://www.python.org/downloads/))
+2. **Node.js 22+** for Javascript dependency management and builds ([Download Node.js](https://nodejs.org/en/download/))
+3. **Poetry 1.8.5** for Python dependency management ([Installation Guide](https://python-poetry.org/docs/#installing-with-the-official-installer)). Use the following command to install Poetry using the official installer:
+  ```shell
+  curl -sSL https://install.python-poetry.org | python3 - --version 1.8.5
+  ```
+4. (Optional) **Podman Compose**. If you are using Docker, you do not need this tool. If you are using Podman, install it with:
+  ```shell
+  pip3 install podman-compose
+  ```
+
+### Windows-Specific Instructions
+
+If developing on Windows, you'll need the following tools:
+
+1. **WSL 2** ([Microsoft WSL Installation Guide](https://docs.microsoft.com/en-us/windows/wsl/install)). Note that WSL 2 may have already been installed when installing Docker or Podman; in that case, you can skip this step.
+2. **Python 3.9+**. Use the following commands to install Python:
+  ```shell
+  # In your WSL terminal:
+  sudo apt update
+  sudo apt upgrade
+  sudo apt upgrade python3
+  sudo apt install python3-pip
+  sudo apt install python3-venv
+  ```
+3. **Poetry 1.8.5**. Use the following command to install Poetry using the official Poetry installer:
+  ```shell
+  # In your WSL terminal:
+  curl -sSL https://install.python-poetry.org | python3 - --version 1.8.5
+  ```
+4. **Node.js 22+** ([Node.js on WSL Installation Guide](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl#install-nvm-nodejs-and-npm))
+5. **Configure Docker Desktop with WSL 2**. Follow the instructions in the [Docker Desktop WSL 2](https://docs.docker.com/desktop/features/wsl/#turn-on-docker-desktop-wsl-2) documentation to enable WSL 2 integration with Docker. If using **Podman**, follow the instructions instead in [Podman Desktop WSL 2](https://podman-desktop.io/docs/installation/windows-install#use-wsl2-as-machine-provider).
+6. (Optional) **Podman Compose**. If you are using Docker, you do not need this tool. If you are using Podman, install it with:
+  ```shell
+  # In your WSL terminal:
+  pip3 install podman-compose
+  ```
+7. **VSCode Remote Development Extension Pack** ([VS Code Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack))
+
+### Repository Setup
+
+Once all the above tools have been installed, clone this repository and open it in VSCode. If on Windows, use the "WSL: Open Folder in WSL" command to open the cloned repository in WSL.
+
+You'll be prompted to install recommended extensions specified in `.vscode/extensions.json`. Click on "Install All" to install them. These include:
+
+- [Python](https://marketplace.visualstudio.com/items/?itemName=ms-python.python): Python language support and debugging
+- [Ruff](https://marketplace.visualstudio.com/items/?itemName=charliermarsh.ruff): Python linting and formatting
+- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint): JavaScript linting and formatting
+- [Even Better TOML](https://marketplace.visualstudio.com/items/?itemName=tamasfe.even-better-toml): TOML file formatting
+
+If you're not automatically prompted, you can install recommended extensions manually by:
+
+1. Opening the Extensions view in VSCode (`Ctrl+Shift+X` or `Cmd+Shift+X`)
+2. Typing "@recommended" in the search bar
+3. Installing each listed extension
 
 ## Contributions
 
 Follow [the NCTR's Python Style Guide](https://github.com/NationalCentreTruthReconciliation/Python-Development-Guide) when making contributions. You can skip the "Setup" section of the guide as this repository already includes the necessary VSCode settings in `.vscode/settings.json`.
 
-## Linting + Formatting
-
-Install the [ESLint VSCode extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint).
+## JavaScript Development
 
-Then, install Node dependencies for development:
+For JavaScript development, you need to install Node dependencies to gain access to the source code, build tools, and linting/formatting:
 
 ```shell
 npm install --include=dev
 ```
 
+You can then use the provided npm scripts for various tasks:
+- `npm run build` - Build JavaScript files for production
+- `npm run watch` - Rebuild JavaScript files whenever they change (see [Re-build JS as Changes are Made](#re-build-js-as-changes-are-made))
+- `npm run lint` - Run ESLint to check JavaScript files
+
 ## Debugging the Application
 
 The ports 8009 and 8010 are exposed to allow you to debug the web application, and the asynchronous job queue, respectively. This functionality is only available when `DEBUG = True`. These ports can be attached to with `debugpy`
@@ -49,13 +124,7 @@ This will re-build the bundled JS files any time you save a change to a `.js` fi
 
 ## Local Python Environment Setup
 
-Python dependencies are managed with [Poetry](https://python-poetry.org/). `poetry` can be installed on your local machine with the [offical installer](https://python-poetry.org/docs/#installing-with-the-official-installer). Install version `1.8.5` with the following command:
-
-```shell
-curl -sSL https://install.python-poetry.org | python3 - --version 1.8.5
-```
-
-Next, create and activate a virtual environment from the root of the repository:
+After installing Poetry as mentioned in the [Setting up Your Development Environment](#setting-up-your-development-environment) section, create and activate a virtual environment from the root of the repository:
 
 ```shell
 python3 -m venv env


Reviews:
user: login: danloveg
body: There are enough differences between using Windows and Mac/Linux that we may want to completely separate out the setup for those situations. WSL is very command-line focused because there's no graphical interface, but Mac/Linux can use the installers for Python and Node just fine.

To further complicate things, when installing Docker and Podman on Windows, you install it using the installer in Windows, but Docker+Podman both use WSL to run the containers.

Since you don't use WSL, if you'd like I can write that section up if you can create a new section for me to write the setup steps in.
state: CHANGES_REQUESTED
author_association: COLLABORATOR
submitted_at: 2025-04-23T19:55:49Z
user: login: yenaing-oo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-24T15:02:38Z
user: login: yenaing-oo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-24T15:06:33Z
user: login: yenaing-oo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-24T15:08:04Z
user: login: danloveg
body: All the required content was there, I just did a bit of re-organizing to make it a bit easier to follow. One example of a change I made is that `podman-compose` is dependent on Python 3 and Pip 3, so I included the installation of that tool *after* the Python installation instructions.

Let me know how these changes look; if everything looks OK then I can approve and merge this in
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-24T15:51:08Z
user: login: danloveg
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-04-24T16:19:20Z

Review comments:
diff_hunk: @@ -6,22 +6,43 @@ The developer documentation here assumes you are using [VSCode](https://code.vis
 
 This application is primarily designed for UNIX-based operating systems (Linux, macOS). Some functionality may not work correctly on Windows.
 
-If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility. You can install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) and then develop within that Linux environment.
+If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility.
+
+## Required Tools
+
+To work on this application, you'll need the following tools:
+
+- **Docker** ([Install Docker](https://docs.docker.com/get-docker/)) or **Podman** ([Install Podman](https://podman.io/getting-started/installation)): For containerized development environment
path: DEVELOPERS.md
user: login: danloveg
body: If a developer uses Podman, they also need to install [podman-compose](https://github.com/containers/podman-compose) as well, since it's a separate tool.

As well, if someone's using WSL, they have to install it in WSL, not in Windows.

Do you think it's worth it to mention installing Docker *Desktop* or Podman *Desktop* instead of just Docker/Podman? You can use each from the command line only, but I think the graphical interface is really helpful for both.
created_at: 2025-04-23T19:40:43Z
author_association: COLLABORATOR
diff_hunk: @@ -6,22 +6,43 @@ The developer documentation here assumes you are using [VSCode](https://code.vis
 
 This application is primarily designed for UNIX-based operating systems (Linux, macOS). Some functionality may not work correctly on Windows.
 
-If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility. You can install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) and then develop within that Linux environment.
+If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility.
+
+## Required Tools
+
+To work on this application, you'll need the following tools:
+
+- **Docker** ([Install Docker](https://docs.docker.com/get-docker/)) or **Podman** ([Install Podman](https://podman.io/getting-started/installation)): For containerized development environment
+- **Python 3.9+** ([Download Python](https://www.python.org/downloads/)): If developing on Windows, install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) instead
+- **Node 22+** ([Download Node.js](https://nodejs.org/en/download/)): For JavaScript dependency management and builds
+- **Poetry 1.8.5** ([Installation Guide](https://python-poetry.org/docs/#installing-with-the-official-installer)): For Python dependency management. Install with:
+  ```shell
+  curl -sSL https://install.python-poetry.org | python3 - --version 1.8.5
+  ```
+- **VSCode** ([Download VSCode](https://code.visualstudio.com/download)): Recommended IDE for development
+- **VSCode Extensions**:
+  - [Python](https://marketplace.visualstudio.com/items/?itemName=ms-python.python): Python language support and debugging
+  - [Ruff](https://marketplace.visualstudio.com/items/?itemName=charliermarsh.ruff): Python linting and formatting
+  - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint): Linting and formatting JS files
+  - [Even Better TOML](https://marketplace.visualstudio.com/items/?itemName=tamasfe.even-better-toml): Formatting TOML files
path: DEVELOPERS.md
user: login: danloveg
body: There's an even better way to recommend these be installed that I found: https://code.visualstudio.com/docs/configure/extensions/extension-marketplace#_workspace-recommended-extensions

Can you create an `extensions.json` file in `.vscode/` with these extensions?
created_at: 2025-04-23T19:51:40Z
author_association: COLLABORATOR
diff_hunk: @@ -6,22 +6,43 @@ The developer documentation here assumes you are using [VSCode](https://code.vis
 
 This application is primarily designed for UNIX-based operating systems (Linux, macOS). Some functionality may not work correctly on Windows.
 
-If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility. You can install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) and then develop within that Linux environment.
+If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility.
+
+## Required Tools
+
+To work on this application, you'll need the following tools:
+
+- **Docker** ([Install Docker](https://docs.docker.com/get-docker/)) or **Podman** ([Install Podman](https://podman.io/getting-started/installation)): For containerized development environment
+- **Python 3.9+** ([Download Python](https://www.python.org/downloads/)): If developing on Windows, install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) instead
path: DEVELOPERS.md
user: login: danloveg
body: I realize the WSL documentation linked here is more comprehensive than just installing Python. If in WSL, you have to install it via the command line and can't use the Python installer.

Can you move the WSL info to below the `- **VSCode**` item, and say something like, if on Windows, follow this guide to set up your development environment in WSL (and then link that documentation).

```suggestion
- **Python 3.9+**
  - If on Mac or Linux, [download Python here](https://www.python.org/downloads/)
  - If on Windows, install Python in WSL using these commands:
  ```shell
  # WSL Installation Instructions
  sudo apt update
  sudo apt upgrade
  sudo apt upgrade python3
  sudo apt install python3-pip
  sudo apt install python3-venv
  ```
```
created_at: 2025-04-23T19:51:42Z
author_association: COLLABORATOR
diff_hunk: @@ -6,22 +6,43 @@ The developer documentation here assumes you are using [VSCode](https://code.vis
 
 This application is primarily designed for UNIX-based operating systems (Linux, macOS). Some functionality may not work correctly on Windows.
 
-If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility. You can install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) and then develop within that Linux environment.
+If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility.
+
+## Required Tools
+
+To work on this application, you'll need the following tools:
+
+- **Docker** ([Install Docker](https://docs.docker.com/get-docker/)) or **Podman** ([Install Podman](https://podman.io/getting-started/installation)): For containerized development environment
+- **Python 3.9+** ([Download Python](https://www.python.org/downloads/)): If developing on Windows, install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) instead
+- **Node 22+** ([Download Node.js](https://nodejs.org/en/download/)): For JavaScript dependency management and builds
+- **Poetry 1.8.5** ([Installation Guide](https://python-poetry.org/docs/#installing-with-the-official-installer)): For Python dependency management. Install with:
+  ```shell
+  curl -sSL https://install.python-poetry.org | python3 - --version 1.8.5
+  ```
path: DEVELOPERS.md
user: login: danloveg
body: These need to be mentioned to be installed in WSL if using Windows
created_at: 2025-04-23T19:52:35Z
author_association: COLLABORATOR
diff_hunk: @@ -6,22 +6,43 @@ The developer documentation here assumes you are using [VSCode](https://code.vis
 
 This application is primarily designed for UNIX-based operating systems (Linux, macOS). Some functionality may not work correctly on Windows.
 
-If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility. You can install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) and then develop within that Linux environment.
+If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility.
+
+## Required Tools
+
+To work on this application, you'll need the following tools:
+
+- **Docker** ([Install Docker](https://docs.docker.com/get-docker/)) or **Podman** ([Install Podman](https://podman.io/getting-started/installation)): For containerized development environment
+- **Python 3.9+** ([Download Python](https://www.python.org/downloads/)): If developing on Windows, install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) instead
+- **Node 22+** ([Download Node.js](https://nodejs.org/en/download/)): For JavaScript dependency management and builds
+- **Poetry 1.8.5** ([Installation Guide](https://python-poetry.org/docs/#installing-with-the-official-installer)): For Python dependency management. Install with:
+  ```shell
+  curl -sSL https://install.python-poetry.org | python3 - --version 1.8.5
+  ```
+- **VSCode** ([Download VSCode](https://code.visualstudio.com/download)): Recommended IDE for development
+- **VSCode Extensions**:
+  - [Python](https://marketplace.visualstudio.com/items/?itemName=ms-python.python): Python language support and debugging
+  - [Ruff](https://marketplace.visualstudio.com/items/?itemName=charliermarsh.ruff): Python linting and formatting
+  - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint): Linting and formatting JS files
+  - [Even Better TOML](https://marketplace.visualstudio.com/items/?itemName=tamasfe.even-better-toml): Formatting TOML files
path: DEVELOPERS.md
user: login: yenaing-oo
body: That's a pretty neat feature to have.

Addressed by: 
https://github.com/NationalCentreTruthReconciliation/Secure-Record-Transfer/pull/519/commits/650d62e460d2e34aa12527075018e12ba8a03724
created_at: 2025-04-24T15:02:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,22 +6,43 @@ The developer documentation here assumes you are using [VSCode](https://code.vis
 
 This application is primarily designed for UNIX-based operating systems (Linux, macOS). Some functionality may not work correctly on Windows.
 
-If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility. You can install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) and then develop within that Linux environment.
+If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility.
+
+## Required Tools
+
+To work on this application, you'll need the following tools:
+
+- **Docker** ([Install Docker](https://docs.docker.com/get-docker/)) or **Podman** ([Install Podman](https://podman.io/getting-started/installation)): For containerized development environment
path: DEVELOPERS.md
user: login: yenaing-oo
body: I think it is worth it to mention _Desktop_ instead of just the CLI + Engine because being able to navigate between logs, start/end containers and browse through a container's filesystem is super convenient.
created_at: 2025-04-24T15:06:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,22 +6,43 @@ The developer documentation here assumes you are using [VSCode](https://code.vis
 
 This application is primarily designed for UNIX-based operating systems (Linux, macOS). Some functionality may not work correctly on Windows.
 
-If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility. You can install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) and then develop within that Linux environment.
+If you're developing on Windows, we recommend using Windows Subsystem for Linux (WSL) to ensure compatibility.
+
+## Required Tools
+
+To work on this application, you'll need the following tools:
+
+- **Docker** ([Install Docker](https://docs.docker.com/get-docker/)) or **Podman** ([Install Podman](https://podman.io/getting-started/installation)): For containerized development environment
+- **Python 3.9+** ([Download Python](https://www.python.org/downloads/)): If developing on Windows, install Python on [WSL](https://code.visualstudio.com/docs/remote/wsl) instead
path: DEVELOPERS.md
user: login: yenaing-oo
body: As you mentioned, I think it would be neater to move the WSL installation instructions to under a new section just for installation instructions for Windows.
created_at: 2025-04-24T15:08:04Z
author_association: CONTRIBUTOR

PR comments:
user: login: yenaing-oo
created_at: 2025-04-24T14:56:51Z
body: @danloveg 
> There are enough differences between using Windows and Mac/Linux that we may want to completely separate out the setup for those situations. WSL is very command-line focused because there's no graphical interface, but Mac/Linux can use the installers for Python and Node just fine.
> 
> To further complicate things, when installing Docker and Podman on Windows, you install it using the installer in Windows, but Docker+Podman both use WSL to run the containers.
> 
> Since you don't use WSL, if you'd like I can write that section up if you can create a new section for me to write the setup steps in.

Thanks for the detailed feedback. As you mentioned, the setup for Windows is quite different from Mac/Linux, so I created a separate section for that. I extracted out tools that are shared for all platforms (VSCode + Extensions and Docker Deskop/Podman Desktop) into its own section as well.

I read up a bit on how to set up a WSL development environment with VSCode and Docker, and filled out some parts of the "Developing on Windows" section that I made, although I'm not sure if I got it right. It would be great if you could help me out on that.

Please feel free to modify any parts as you see fit, or leave feedback for me to work on.
author_association: CONTRIBUTOR
user: login: yenaing-oo
created_at: 2025-04-24T16:08:46Z
body: > All the required content was there, I just did a bit of re-organizing to make it a bit easier to follow. One example of a change I made is that `podman-compose` is dependent on Python 3 and Pip 3, so I included the installation of that tool _after_ the Python installation instructions.
> 
> Let me know how these changes look; if everything looks OK then I can approve and merge this in

Everything looks great! I like how you made a new section for "Repository Setup". It's much easier to read that way.

One last thing - what do you think about removing [this line](https://github.com/NationalCentreTruthReconciliation/Secure-Record-Transfer/blob/2ebd9e853e67fb2f25d834f13585d47f01b94306/DEVELOPERS.md?plain=1#L3)? It seems redundant since we are recommending usage of VSCode in the setup instructions.
author_association: CONTRIBUTOR
user: login: danloveg
created_at: 2025-04-24T16:11:09Z
body: > > All the required content was there, I just did a bit of re-organizing to make it a bit easier to follow. One example of a change I made is that `podman-compose` is dependent on Python 3 and Pip 3, so I included the installation of that tool _after_ the Python installation instructions.
> > Let me know how these changes look; if everything looks OK then I can approve and merge this in
> 
> Everything looks great! I like how you made a new section for "Repository Setup". It's much easier to read that way.
> 
> One last thing - what do you think about removing [this line](https://github.com/NationalCentreTruthReconciliation/Secure-Record-Transfer/blob/2ebd9e853e67fb2f25d834f13585d47f01b94306/DEVELOPERS.md?plain=1#L3)? It seems redundant since we are recommending usage of VSCode in the setup instructions.

Good catch, how does it look now?
author_association: COLLABORATOR
user: login: yenaing-oo
created_at: 2025-04-24T16:14:23Z
body: > > > All the required content was there, I just did a bit of re-organizing to make it a bit easier to follow. One example of a change I made is that `podman-compose` is dependent on Python 3 and Pip 3, so I included the installation of that tool _after_ the Python installation instructions.
> > > Let me know how these changes look; if everything looks OK then I can approve and merge this in
> > 
> > 
> > Everything looks great! I like how you made a new section for "Repository Setup". It's much easier to read that way.
> > One last thing - what do you think about removing [this line](https://github.com/NationalCentreTruthReconciliation/Secure-Record-Transfer/blob/2ebd9e853e67fb2f25d834f13585d47f01b94306/DEVELOPERS.md?plain=1#L3)? It seems redundant since we are recommending usage of VSCode in the setup instructions.
> 
> Good catch, how does it look now?

That looks good to me. Feel free to merge this in now.
author_association: CONTRIBUTOR