From 907d2ce7e1b7a7cd958b6946558e200337a192ce Mon Sep 17 00:00:00 2001
From: JeremyEastham <34139712+JeremyEastham@users.noreply.github.com>
Date: Sat, 16 Apr 2022 18:15:00 -0500
Subject: [PATCH 01/12] Remove race condition in
 AuthRecipeTest.paginationTest()

---
 src/test/java/io/supertokens/test/AuthRecipeTest.java | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/test/java/io/supertokens/test/AuthRecipeTest.java b/src/test/java/io/supertokens/test/AuthRecipeTest.java
index 5280679b5..3ea5601c2 100644
--- a/src/test/java/io/supertokens/test/AuthRecipeTest.java
+++ b/src/test/java/io/supertokens/test/AuthRecipeTest.java
@@ -205,8 +205,11 @@ public void paginationTest() throws Exception {
         }
 
         UserInfo user1 = EmailPassword.signUp(process.getProcess(), "test0@example.com", "password0");
+        Thread.sleep(1); // Sleep to remove race condition
         UserInfo user2 = EmailPassword.signUp(process.getProcess(), "test1@example.com", "password1");
+        Thread.sleep(1);
         UserInfo user3 = EmailPassword.signUp(process.getProcess(), "test20@example.com", "password2");
+        Thread.sleep(1);
         UserInfo user4 = EmailPassword.signUp(process.getProcess(), "test3@example.com", "password3");
 
         {

From 78bc0e96320ae1f2dd4f391212fe56e33b9f86dd Mon Sep 17 00:00:00 2001
From: JeremyEastham <34139712+JeremyEastham@users.noreply.github.com>
Date: Sat, 16 Apr 2022 18:24:46 -0500
Subject: [PATCH 02/12] Make file operations work cross-platform

---
 .../io/supertokens/test/ConfigTest2_6.java    | 10 +--
 .../java/io/supertokens/test/LoggingTest.java |  5 +-
 src/test/java/io/supertokens/test/Utils.java  | 73 ++++++-------------
 .../java/io/supertokens/test/VersionTest.java |  4 +-
 4 files changed, 32 insertions(+), 60 deletions(-)

diff --git a/src/test/java/io/supertokens/test/ConfigTest2_6.java b/src/test/java/io/supertokens/test/ConfigTest2_6.java
index 6f9f04d74..30f85bc9a 100644
--- a/src/test/java/io/supertokens/test/ConfigTest2_6.java
+++ b/src/test/java/io/supertokens/test/ConfigTest2_6.java
@@ -29,6 +29,8 @@
 import org.junit.rules.TestRule;
 
 import java.io.File;
+import java.io.FileNotFoundException;
+import java.nio.file.Files;
 
 import static junit.framework.TestCase.assertEquals;
 import static junit.framework.TestCase.assertFalse;
@@ -165,16 +167,12 @@ public void testThatNonTestingConfigValuesThrowErrors() throws Exception {
     public void testThatMissingConfigFileThrowsError() throws Exception {
         String[] args = { "../" };
 
-        ProcessBuilder pb = new ProcessBuilder("rm", "config.yaml");
-        pb.directory(new File(args[0]));
-        Process process1 = pb.start();
-        process1.waitFor();
+        Files.delete(new File(args[0] + "config.yaml").toPath());
 
         TestingProcess process = TestingProcessManager.start(args);
         ProcessState.EventAndException e = process.checkOrWaitForEvent(ProcessState.PROCESS_STATE.INIT_FAILURE);
         assertNotNull(e);
-        assertEquals(e.exception.getMessage(),
-                "java.io.FileNotFoundException: ../config.yaml (No such file or directory)");
+        assertTrue(e.exception.getCause() instanceof FileNotFoundException);
 
         process.kill();
         assertNotNull(process.checkOrWaitForEvent(PROCESS_STATE.STOPPED));
diff --git a/src/test/java/io/supertokens/test/LoggingTest.java b/src/test/java/io/supertokens/test/LoggingTest.java
index 63fccf5cc..aeb25e316 100644
--- a/src/test/java/io/supertokens/test/LoggingTest.java
+++ b/src/test/java/io/supertokens/test/LoggingTest.java
@@ -254,11 +254,10 @@ public void testThatSubFoldersAreCreated() throws Exception {
             assertFalse(logFile.isDirectory());
 
         } finally {
-
-            FileUtils.deleteDirectory(new File("../temp/a"));
-
             process.kill();
             assertNotNull(process.checkOrWaitForEvent(PROCESS_STATE.STOPPED));
+
+            FileUtils.deleteDirectory(new File("../temp/a"));
         }
 
     }
diff --git a/src/test/java/io/supertokens/test/Utils.java b/src/test/java/io/supertokens/test/Utils.java
index 611ecd0d7..1a0934b6b 100644
--- a/src/test/java/io/supertokens/test/Utils.java
+++ b/src/test/java/io/supertokens/test/Utils.java
@@ -31,22 +31,21 @@
 
 import java.io.*;
 import java.nio.charset.StandardCharsets;
-import java.nio.file.Files;
+import java.nio.file.*;
 import java.util.Arrays;
+import java.util.regex.Pattern;
 
 public abstract class Utils extends Mockito {
 
     private static ByteArrayOutputStream byteArrayOutputStream;
+    private static final String newLine = System.lineSeparator();
 
     public static void afterTesting() {
         String installDir = "../";
         try {
 
             // remove config.yaml file
-            ProcessBuilder pb = new ProcessBuilder("rm", "config.yaml");
-            pb.directory(new File(installDir));
-            Process process = pb.start();
-            process.waitFor();
+            Files.delete(new File(installDir + "config.yaml").toPath()); // Use behavior of rm command
 
             // remove webserver-temp folders created by tomcat
             final File webserverTemp = new File(installDir + "webserver-temp");
@@ -105,22 +104,18 @@ public static void reset() {
         Main.makeConsolePrintSilent = true;
         String installDir = "../";
         try {
-
             // if the default config is not the same as the current config, we must reset the storage layer
-            File ogConfig = new File("../temp/config.yaml");
-            File currentConfig = new File("../config.yaml");
-            if (currentConfig.isFile()) {
-                byte[] ogConfigContent = Files.readAllBytes(ogConfig.toPath());
-                byte[] currentConfigContent = Files.readAllBytes(currentConfig.toPath());
+            Path ogConfig = new File(installDir + "temp/config.yaml").toPath();
+            Path currentConfig = new File(installDir + "config.yaml").toPath();
+            if (currentConfig.toFile().isFile()) {
+                byte[] ogConfigContent = Files.readAllBytes(ogConfig);
+                byte[] currentConfigContent = Files.readAllBytes(currentConfig);
                 if (!Arrays.equals(ogConfigContent, currentConfigContent)) {
                     StorageLayer.close();
                 }
             }
 
-            ProcessBuilder pb = new ProcessBuilder("cp", "temp/config.yaml", "./config.yaml");
-            pb.directory(new File(installDir));
-            Process process = pb.start();
-            process.waitFor();
+            Files.copy(ogConfig, currentConfig, StandardCopyOption.REPLACE_EXISTING); // Use behavior of cp command
 
             // in devConfig, it's set to false. However, in config, it's commented. So we comment it out so that it
             // mimics production. Refer to https://github.com/supertokens/supertokens-core/issues/118
@@ -138,46 +133,26 @@ public static void reset() {
         System.gc();
     }
 
-    static void commentConfigValue(String key) throws IOException {
+    private static void replaceConfigValue(String regex, String newStr) throws IOException {
         // we close the storage layer since there might be a change in the db related config.
         StorageLayer.close();
+        Path configPath = new File("../config.yaml").toPath();
+        String originalFileContent = Files.readString(configPath);
+        String modifiedFileContent = originalFileContent.replaceAll(regex, newStr);
+        String normalizedFileContent = modifiedFileContent.replaceAll("\r?\n", newLine); // Normalize line endings
+        Files.writeString(configPath, normalizedFileContent);
+    }
 
-        String oldStr = "\n((#\\s)?)" + key + "(:|((:\\s).+))\n";
-        String newStr = "\n# " + key + ":";
-
-        StringBuilder originalFileContent = new StringBuilder();
-        try (BufferedReader reader = new BufferedReader(new FileReader("../config.yaml"))) {
-            String currentReadingLine = reader.readLine();
-            while (currentReadingLine != null) {
-                originalFileContent.append(currentReadingLine).append(System.lineSeparator());
-                currentReadingLine = reader.readLine();
-            }
-            String modifiedFileContent = originalFileContent.toString().replaceAll(oldStr, newStr);
-            try (BufferedWriter writer = new BufferedWriter(new FileWriter("../config.yaml"))) {
-                writer.write(modifiedFileContent);
-            }
-        }
-
+    public static void commentConfigValue(String key) throws IOException {
+        String find = "\r?\n#?\\s*" + Pattern.quote(key) + ":.*\r?\n";
+        String replace = newLine + "# " + key + ":" + newLine;
+        replaceConfigValue(find, replace);
     }
 
     public static void setValueInConfig(String key, String value) throws IOException {
-        // we close the storage layer since there might be a change in the db related config.
-        StorageLayer.close();
-
-        String oldStr = "\n((#\\s)?)" + key + "(:|((:\\s).+))\n";
-        String newStr = "\n" + key + ": " + value + "\n";
-        StringBuilder originalFileContent = new StringBuilder();
-        try (BufferedReader reader = new BufferedReader(new FileReader("../config.yaml"))) {
-            String currentReadingLine = reader.readLine();
-            while (currentReadingLine != null) {
-                originalFileContent.append(currentReadingLine).append(System.lineSeparator());
-                currentReadingLine = reader.readLine();
-            }
-            String modifiedFileContent = originalFileContent.toString().replaceAll(oldStr, newStr);
-            try (BufferedWriter writer = new BufferedWriter(new FileWriter("../config.yaml"))) {
-                writer.write(modifiedFileContent);
-            }
-        }
+        String find = "\r?\n#?\\s*" + Pattern.quote(key) + ":.*\r?\n";
+        String replace = newLine + "# " + key + ": " + value + newLine;
+        replaceConfigValue(find, replace);
     }
 
     public static TestRule getOnFailure() {
diff --git a/src/test/java/io/supertokens/test/VersionTest.java b/src/test/java/io/supertokens/test/VersionTest.java
index c5eb45fd4..29bdee4a0 100644
--- a/src/test/java/io/supertokens/test/VersionTest.java
+++ b/src/test/java/io/supertokens/test/VersionTest.java
@@ -28,6 +28,7 @@
 import org.junit.rules.TestRule;
 
 import java.io.File;
+import java.io.FileNotFoundException;
 
 import static junit.framework.TestCase.assertEquals;
 import static org.junit.Assert.assertNotNull;
@@ -90,8 +91,7 @@ public void versionFileMissingTest() throws Exception {
 
             ProcessState.EventAndException e = process.checkOrWaitForEvent(ProcessState.PROCESS_STATE.INIT_FAILURE);
             assertNotNull(e);
-            assertEquals(e.exception.getMessage(),
-                    "java.io.FileNotFoundException: ../version.yaml (No such file or directory)");
+            assertTrue(e.exception.getCause() instanceof FileNotFoundException);
 
             process.kill();
             assertNotNull(process.checkOrWaitForEvent(ProcessState.PROCESS_STATE.STOPPED));

From f6d1c0921525e3dab7af9954d593dbd1ba26add4 Mon Sep 17 00:00:00 2001
From: Jeremy E <34139712+JeremyEastham@users.noreply.github.com>
Date: Sat, 16 Apr 2022 20:24:40 -0500
Subject: [PATCH 03/12] Major update to CONTRIBUTING.md

- Add Windows development instructions
- Refactor links to the bottom
- Fix formatting, grammar, and punctuation
---
 CONTRIBUTING.md | 249 ++++++++++++++++++++++++++++++++----------------
 1 file changed, 169 insertions(+), 80 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2dcf88472..687c9dfb4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,118 +3,207 @@
 We're so excited you're interested in helping with SuperTokens! We are happy to help you get started, even if you don't have any previous open-source experience :blush:
 
 ## New to Open Source?
-1. Take a look at [How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github)
-2. Go through the [SuperTokens Code of Conduct](https://github.com/supertokens/supertokens-core/blob/master/CODE_OF_CONDUCT.md)
+1. Take a look at [How to Contribute to an Open Source Project on GitHub][how-to-contribute-to-open-source]
+2. Go through the [SuperTokens Code of Conduct][code-of-conduct]
 
-## Where to ask Questions?
-1. Check our [Github Issues](https://github.com/supertokens/supertokens-core/issues) to see if someone has already answered your question.  
-2. Join our community on [Discord](https://supertokens.io/discord) and feel free to ask us your questions  
+## Where to Ask Questions?
+1. Check our [Github Issues][issues] to see if someone has already answered your question.
+2. Join our community on [Discord][discord] and feel free to ask us your questions
 
-As you gain experience with SuperTokens, please help answer other people's questions! :pray: 
+As you gain experience with SuperTokens, please help answer other people's questions! :pray:
 
 ## What to Work On?
-You can get started by taking a look at our [Github issues](https://github.com/supertokens/supertokens-core/issues)  
-If you find one that looks interesting and no one else is already working on it, comment in the issue that you are going to work on it.  
+You can get started by taking a look at our [Github Issues][issues]  
+If you find one that looks interesting and no one else is already working on it, comment in the issue that you are going to work on it.
 
-Please ask as many questions as you need, either directly in the issue or on [Discord](https://supertokens.io/discord). We're happy to help!:raised_hands:
-
-### Contributions that are ALWAYS welcome 
+Please ask as many questions as you need, either directly in the issue or on [Discord][discord]. We're happy to help! :raised_hands:
 
+### Contributions that are ALWAYS welcome
 1. More tests
-2. Contributing to discussions that can be found [here](https://github.com/supertokens/supertokens-core/issues?q=is%3Aissue+is%3Aopen+label%3Adiscussions)
+2. Contributing to discussions that can be found [here][issues-discussions]
 3. Improved error messages
 4. Educational content like blogs, videos, courses
 
-
 ## Development Setup
 
 ### With Gitpod
-1. Navigate to the [supertokens-root](https://github.com/supertokens/supertokens-root) repository
+1. Navigate to the [supertokens-root][supertokens-root] repository
 2. Click on the `Open in Gitpod` button
 
 ### Local Setup Prerequisites
-- OS: Linux or macOS. Or if using Windows, you need to use [wsl2](https://docs.microsoft.com/en-us/windows/wsl/about).
-- JDK: openjdk 15.0.1. Installation instructions for Mac and Linux can be found in [our wiki](https://github.com/supertokens/supertokens-core/wiki/Installing-OpenJDK-for-Mac-and-Linux)
-- IDE: [IntelliJ](https://www.jetbrains.com/idea/download/)(recommended) or equivalent IDE
-
-### Familiarize yourself with SuperTokens
-1. [Architecture of SuperTokens](https://github.com/supertokens/supertokens-core/wiki/SuperTokens-Architecture)
-2. [SuperTokens code and file structure overview](https://github.com/supertokens/supertokens-core/wiki/Code-and-file-structure-overview)
-3. [Versioning methodology](https://github.com/supertokens/supertokens-core/wiki/Versioning,-git-and-releases)
-
+- OS: Linux or macOS. Windows is experimentally supported with Git Bash (recommended, installed with [Git for Windows][git-for-windows]) or [WSL2][wsl-about].
+- JDK: OpenJDK 15.0.1
+    - Installation instructions for Mac and Linux can be found in [our wiki][wiki-openjdk-install-instructions-mac-linux]
+    - To install for Windows, download and run the correct installer from the [AdoptOpenJDK Archive][adopt-openjdk-archive]
+- IDE: [IntelliJ IDEA][intellij] (recommended) or equivalent IDE
+
+### Familiarize Yourself with SuperTokens
+1. [Architecture of SuperTokens][wiki-architecture]
+2. [SuperTokens Code and File Structure Overview][wiki-overview]
+3. [Versioning methodology][wiki-versioning]
+
+### Experimental Windows Setup ([Git Bash][git-for-windows]) [Recommended]
+1. Git Bash is automatically installed with [Git for Windows][git-for-windows]
+2. Install the correct version of OpenJDK (see above) from [AdoptOpenJDK][adopt-openjdk-archive]
+3. Open Command Prompt or PowerShell and run `sh` to open Git Bash
+4. Run `echo "TERM=cygwin" >> .bashrc`
+    - This ensures that the correct encoding is used in the console, especially when running `gradle` commands
+5. Run `git config --global core.autocrlf false`
+    - This ensures that line endings are not converted to Windows (CRLF) line endings on checkout
+    - Scripts will fail if line endings are CRLF
+6. Follow the Project Setup below (using Git Bash)
+7. If using IntelliJ IDEA:
+    - Go to `File > Project Structure... > Project Settings > Project` and set `Project SDK` to the correct OpenJDK version
+    - Go to `File > Settings... > Tools > Terminal` and set `Application Settings > Shell Path` to the location of Git Bash
+        - For the default install directory this is `C:\Program Files\Git\bin\bash.exe`
+        - This will allow you to open a shell script and click the play button to run it and create a template run configuration
+8. If using a Git GUI Client (GitHub Desktop, SourceTree, GitKraken, etc):
+    - Make sure that Git Bash is set as the default terminal
+        - This ensures that any pre-commit hooks can be run
+9. If NOT using a Git GUI Client:
+    - Make sure to use Git from the Git Bash shell
+        - This ensures that any pre-commit hooks can be run
+
+### Experimental Windows Setup ([WSL2][wsl-about])
+1. If WSL2 is not installed, follow [Microsoft's installation instructions][wsl-install]
+2. Open Command Prompt, PowerShell, or the Ubuntu Profile in Windows Terminal
+3. If not using Ubuntu Profile in Windows Terminal, run `wsl` to open bash
+4. Follow Linux setup instructions for [installing OpenJDK][wiki-openjdk-install-instructions-mac-linux]
+5. Follow the Project Setup below
+    - Note: If using IntelliJ IDEA Community, checkout into the WSL filesystem, not Windows
+        - Running Windows files in WSL is only supported in IntelliJ IDEA Ultimate
+6. If using IntelliJ IDEA:
+    - Go to `File > Project Structure... > Project Settings > Project` and set `Project SDK` to the correct WSL OpenJDK version
+7. If using a Git GUI Client (GitHub Desktop, SourceTree, GitKraken, etc):
+    - Make sure that WSL Bash is set as the default terminal
+        - **This option does not have widespread support**
+        - This ensures that any pre-commit hooks can be run
+8. If NOT using a Git GUI Client:
+    - Make sure to use Git from the WSL Bash shell
+        - This ensures that any pre-commit hooks can be run
 
 ### Project Setup
-1. Fork the [supertokens-core](https://github.com/supertokens/supertokens-core) repository (**Skip this step if you are NOT modifying supertokens-core**)
-2. `git clone https://github.com/supertokens/supertokens-root.git`
-3. `cd supertokens-root`
+1. Fork the [supertokens-core][supertokens-core] repository (**Skip this step if you are NOT modifying supertokens-core**)
+2. Run `git clone https://github.com/supertokens/supertokens-root.git`
+3. Run `cd supertokens-root`
 4. Open the `modules.txt` file in an editor (**Skip this step if you are NOT modifying supertokens-core**):
-    - The `modules.txt` file contains the core, plugin-interface, the type of plugin and their branches(versions) 
-    - By default the `master` branch is used but you can change the branch depending on which version you want to modify 
+    - The `modules.txt` file contains the core, plugin-interface, the type of plugin and their branches(versions)
+    - By default, the `master` branch is used, but you can change the branch depending on which version you want to modify
     - The `sqlite-plugin` is used as the default plugin as it is an in-memory database and requires no setup
-      - [core](https://github.com/supertokens/supertokens-core)
-      - [plugin-interface](https://github.com/supertokens/supertokens-plugin-interface)
-      - Check the repository branches by clicking on the links listed above, click the branch tab and check for all the available versions 
-    - Add your github `username` separated by a ',' after `core,master` in  `modules.txt`
-    - If, for example, your github `username` is `helloworld` then modules.txt should look like...  
+        - [core][supertokens-core]
+        - [plugin-interface][supertokens-plugin-interface]
+        - Check the repository branches by clicking on the links listed above, click the branch tab to view all the available versions
+    - Add your GitHub `username` separated by a ',' after `core,master` in  `modules.txt`
+    - If, for example, your GitHub `username` is `helloworld` then modules.txt should look like:
       ```
       // put module name like module name,branch name,github username(if contributing with a forked repository) and then call ./loadModules script        
-      core,master,helloworld  
-      plugin-interface,master        
+      core,master,helloworld
+      plugin-interface,master
       sqlite-plugin,master
       ```
-	
-5. Run loadModules to clone the required repositories  
-`./loadModules`
-
-
-## Modifying code
-1. Open `supetokens-root` in your IDE
-2. After gradle has imported all the dependencies you can start modifying the code  
-
-## Testing  
-
-### On your local machine
-1. Navigate to the `supertokens-root` repository  
-2. Run all tests   
-`./startTestingEnv`  
-3. If all tests pass the terminal should display  
-- core tests:  
-![core tests passing](https://github.com/supertokens/supertokens-logo/blob/master/images/core-tests-passing.png)  
-- plugin tests:  
-![plugin tests passing](https://github.com/supertokens/supertokens-logo/blob/master/images/plugin-tests-passing.png)
-
-### Using github actions
-1. Go to the supertokens-core repo on github (or your forked version of it).
-2. Navigate to the Actions tab.
-3. Find the action named "Run tests" and navigate to it.
-4. Click on the "Run workflow" button.
+5. Run `./loadModules` to clone the required repositories
+6. Open `supertokens-root` in your IDE ([IntelliJ IDEA][intellij] is recommended)
+7. After gradle has imported all the dependencies you can start modifying the code
+
+## Testing
+
+### Running All Tests ([IntelliJ IDEA][intellij])
+1. Make sure that the `Start Testing Environment` run configuration and `./startTestingEnv` are not running
+2. Run the `Run All Tests` run configuration
+
+### Running Single Tests ([IntelliJ IDEA][intellij])
+1. Run the `Start Testing Environment` run configuration
+2. Wait for it to print `Test environment running...`
+3. Leave this script running in the terminal
+4. Click the Play button next to the test(s) that you want to run
+
+### Running All Tests (Manually)
+1. Navigate to the `supertokens-root` repository
+2. Run `./startTestingEnv`
+3. If all tests pass the terminal should display
+   - Core Tests:  
+     ![core tests passing][image-core-tests-passing]
+   - Plugin Tests:  
+     ![plugin tests passing][image-plugin-tests-passing]
+
+### Running All Tests (GitHub Actions)
+1. Go to the supertokens-core repo on GitHub (or your forked version of it)
+2. Navigate to the Actions tab
+3. Find the action named "Run tests" and navigate to it
+4. Click on the "Run workflow" button
 5. Set the config variables in the drop down:
-    - **supertokens-plugin-interface repo owner name**: If you have forked the supertokens-plugin-interface repo, then set the value of this to your github username.
-    - **supertokens-plugin-interface repos branch name**: If the core version you are working on is compatible with a plugin-interface version that is not in the master branch, then set the correct branch name in this value.
-6. Click on "Run workflow".
+    - **supertokens-plugin-interface repo owner name**: If you have forked the supertokens-plugin-interface repo, then set the value of this to your GitHub username
+    - **supertokens-plugin-interface repos branch name**: If the core version you are working on is compatible with a plugin-interface version that is not in the master branch, then set the correct branch name in this value
+6. Click on "Run workflow"
 
-## Running the core manually
+## Running the Core (Manually)
 1. Run `startTestingEnv --wait` in a terminal, and keep it running
 2. Then open `supertokens-root` in another terminal and run `cp ./temp/config.yaml .`
-3. Then run `java -classpath "./core/*:./plugin-interface/*" io.supertokens.Main ./ DEV`. This will start the core to listen on `http://localhost:3567`
+3. Then run `java -classpath "./supertokens-core/*:./supertokens-plugin-interface/*" io.supertokens.Main ./ DEV`. This will start the core to listen on `http://localhost:3567`
 
-## Pull Request
-1. Before submitting a pull request make sure all tests have passed  
+## Pull Requests
+1. Before submitting a pull request make sure all tests have passed
 2. Reference the relevant issue or pull request and give a clear description of changes/features added when submitting a pull request
-3. Make sure the PR title follows [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) specification
+3. Make sure the PR title follows [conventional commits][conventional-commits] specification
+
+## SuperTokens Community
+SuperTokens is made possible by a passionate team and a strong community of developers. If you have any questions or would like to get more involved in the SuperTokens community you can check out:
+- [Github Issues][issues]
+- [Discord][discord]
+- [Twitter][twitter]
+- or [Email Us][email]
+
+### Additional Resources
+- [SuperTokens Docs][docs]
+- [Blog Posts][blog]
+- [Development Guideline for Backend and Frontend Recipes][wiki-recipe-development-guide]
+
+[how-to-contribute-to-open-source]: https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github
+
+[code-of-conduct]: https://github.com/supertokens/supertokens-core/blob/master/CODE_OF_CONDUCT.md
+
+[supertokens-root]: https://github.com/supertokens/supertokens-root
+
+[supertokens-core]: https://github.com/supertokens/supertokens-core
+
+[supertokens-plugin-interface]: https://github.com/supertokens/supertokens-plugin-interface
+
+[issues]: https://github.com/supertokens/supertokens-core/issues
+
+[issues-discussions]: https://github.com/supertokens/supertokens-core/issues?q=is%3Aissue+is%3Aopen+label%3Adiscussions
+
+[discord]: https://supertokens.io/discord
+
+[twitter]: https://twitter.com/supertokensio
+
+[email]: mailto:team@supertokens.io
+
+[blog]: https://supertokens.io/blog/
+
+[docs]: https://supertokens.io/docs/community/getting-started/installation
+
+[wiki-recipe-development-guide]: https://github.com/supertokens/supertokens-core/wiki/Development-guideline-for-the-backend-and-frontend-recipes
+
+[wiki-openjdk-install-instructions-mac-linux]: https://github.com/supertokens/supertokens-core/wiki/Installing-OpenJDK-for-Mac-and-Linux
+
+[wiki-architecture]: https://github.com/supertokens/supertokens-core/wiki/SuperTokens-Architecture
+
+[wiki-overview]: https://github.com/supertokens/supertokens-core/wiki/Code-and-file-structure-overview
+
+[wiki-versioning]: https://github.com/supertokens/supertokens-core/wiki/Versioning,-git-and-releases
+
+[git-for-windows]: https://gitforwindows.org/
+
+[wsl-about]: https://docs.microsoft.com/en-us/windows/wsl/about
+
+[wsl-install]: https://docs.microsoft.com/en-us/windows/wsl/install
 
-## SuperTokens Community 
-SuperTokens is made possible by a passionate team and a strong community of developers. If you have any questions or would like to get more involved in the SuperTokens community you can check out:  
-  - [Github Issues](https://github.com/supertokens/supertokens-core/issues)
-  - [Discord](https://supertokens.io/discord)
-  - [Twitter](https://twitter.com/supertokensio)
-  - or [email us](mailto:team@supertokens.io)
-  
-Additional resources you might find useful:
-  - [SuperTokens Docs](https://supertokens.io/docs/community/getting-started/installation)
-  - [Blog Posts](https://supertokens.io/blog/)
-  - [Development guideline for the backend and frontend recipes](https://github.com/supertokens/supertokens-core/wiki/Development-guideline-for-the-backend-and-frontend-recipes)
+[intellij]: https://www.jetbrains.com/idea/
 
+[adopt-openjdk-archive]: https://adoptopenjdk.net/archive.html
 
+[conventional-commits]: https://www.conventionalcommits.org/en/v1.0.0/
 
+[image-core-tests-passing]: https://github.com/supertokens/supertokens-logo/blob/master/images/core-tests-passing.png
 
+[image-plugin-tests-passing]: https://github.com/supertokens/supertokens-logo/blob/master/images/plugin-tests-passing.png
\ No newline at end of file

From 40165cf9267d8a4c99581c0216a1aa2be93df28d Mon Sep 17 00:00:00 2001
From: Jeremy E <34139712+JeremyEastham@users.noreply.github.com>
Date: Sat, 16 Apr 2022 20:26:05 -0500
Subject: [PATCH 04/12] Update CHANGELOG.md

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e5a9a666d..83ccee7c1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - Fixes base_path config option not being observed when running `supertokens list`
 - Adds base_path normalization logic
+- Adds experimental Windows support via Git Bash and WSL2
 
 ## [3.12.1] - 2022-04-02
 

From 07bb14988697c1aab4e146f1880fb3a7b4ab78e9 Mon Sep 17 00:00:00 2001
From: Jeremy E <34139712+JeremyEastham@users.noreply.github.com>
Date: Mon, 18 Apr 2022 14:52:05 -0500
Subject: [PATCH 05/12] Fix Utils.setValueInConfig()

---
 src/test/java/io/supertokens/test/Utils.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/test/java/io/supertokens/test/Utils.java b/src/test/java/io/supertokens/test/Utils.java
index 1a0934b6b..c291785a0 100644
--- a/src/test/java/io/supertokens/test/Utils.java
+++ b/src/test/java/io/supertokens/test/Utils.java
@@ -151,7 +151,7 @@ public static void commentConfigValue(String key) throws IOException {
 
     public static void setValueInConfig(String key, String value) throws IOException {
         String find = "\r?\n#?\\s*" + Pattern.quote(key) + ":.*\r?\n";
-        String replace = newLine + "# " + key + ": " + value + newLine;
+        String replace = newLine + key + ": " + value + newLine;
         replaceConfigValue(find, replace);
     }
 

From 2ee4d6f7f3a9e5948e209108f2ca641d33387f71 Mon Sep 17 00:00:00 2001
From: Jeremy E <34139712+JeremyEastham@users.noreply.github.com>
Date: Mon, 18 Apr 2022 16:23:06 -0500
Subject: [PATCH 06/12] Fix WebserverTest.differentHostNameTest()

Remove testing connection from local address, since this test could fail depending on firewall configuration
---
 .../io/supertokens/test/WebserverTest.java     | 18 +-----------------
 1 file changed, 1 insertion(+), 17 deletions(-)

diff --git a/src/test/java/io/supertokens/test/WebserverTest.java b/src/test/java/io/supertokens/test/WebserverTest.java
index 79569924a..04a70465e 100644
--- a/src/test/java/io/supertokens/test/WebserverTest.java
+++ b/src/test/java/io/supertokens/test/WebserverTest.java
@@ -42,9 +42,7 @@
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 import java.io.IOException;
-import java.net.ConnectException;
-import java.net.InetAddress;
-import java.net.SocketTimeoutException;
+import java.net.*;
 import java.util.HashMap;
 
 import static org.junit.Assert.*;
@@ -597,26 +595,12 @@ public void differentHostNameTest() throws InterruptedException, IOException, Ht
         Utils.setValueInConfig("host", "\"localhost\"");
         hello("localhost", "3567");
         hello("127.0.0.1", "3567");
-        try {
-            hello(inetAddress.getHostAddress(), "3567");
-            if (!inetAddress.getHostAddress().equals("127.0.0.1")) {
-                fail();
-            }
-        } catch (ConnectException ignored) {
-        }
 
         Utils.reset();
 
         Utils.setValueInConfig("host", "\"127.0.0.1\"");
         hello("localhost", "3567");
         hello("127.0.0.1", "3567");
-        try {
-            hello(inetAddress.getHostAddress(), "3567");
-            if (!inetAddress.getHostAddress().equals("127.0.0.1")) {
-                fail();
-            }
-        } catch (ConnectException ignored) {
-        }
 
         Utils.reset();
 

From d99e0f4ef5d2a752dc6ad1d240fbd4d08543cada Mon Sep 17 00:00:00 2001
From: Jeremy E <34139712+JeremyEastham@users.noreply.github.com>
Date: Wed, 20 Apr 2022 14:18:26 -0500
Subject: [PATCH 07/12] Add Project Setup links to `CONTRIBUTING.md`

---
 CONTRIBUTING.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 687c9dfb4..efb07bf5e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,7 +51,7 @@ Please ask as many questions as you need, either directly in the issue or on [Di
 5. Run `git config --global core.autocrlf false`
     - This ensures that line endings are not converted to Windows (CRLF) line endings on checkout
     - Scripts will fail if line endings are CRLF
-6. Follow the Project Setup below (using Git Bash)
+6. Follow the instructions for [Project Setup](#project-setup) below (using Git Bash)
 7. If using IntelliJ IDEA:
     - Go to `File > Project Structure... > Project Settings > Project` and set `Project SDK` to the correct OpenJDK version
     - Go to `File > Settings... > Tools > Terminal` and set `Application Settings > Shell Path` to the location of Git Bash
@@ -69,7 +69,7 @@ Please ask as many questions as you need, either directly in the issue or on [Di
 2. Open Command Prompt, PowerShell, or the Ubuntu Profile in Windows Terminal
 3. If not using Ubuntu Profile in Windows Terminal, run `wsl` to open bash
 4. Follow Linux setup instructions for [installing OpenJDK][wiki-openjdk-install-instructions-mac-linux]
-5. Follow the Project Setup below
+5. Follow the instructions for [Project Setup](#project-setup) below (using WSL Bash)
     - Note: If using IntelliJ IDEA Community, checkout into the WSL filesystem, not Windows
         - Running Windows files in WSL is only supported in IntelliJ IDEA Ultimate
 6. If using IntelliJ IDEA:

From 3e295efe87cde517412b4cd82daa7a1bad50723c Mon Sep 17 00:00:00 2001
From: Jeremy E <34139712+JeremyEastham@users.noreply.github.com>
Date: Wed, 20 Apr 2022 14:23:40 -0500
Subject: [PATCH 08/12] Observe visibility of `.testEnvRunning` before running
 tests

---
 src/test/java/io/supertokens/test/Utils.java | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/test/java/io/supertokens/test/Utils.java b/src/test/java/io/supertokens/test/Utils.java
index c291785a0..11b6f7559 100644
--- a/src/test/java/io/supertokens/test/Utils.java
+++ b/src/test/java/io/supertokens/test/Utils.java
@@ -18,6 +18,7 @@
 
 import com.google.gson.JsonObject;
 import io.supertokens.Main;
+import io.supertokens.exceptions.QuitProgramException;
 import io.supertokens.pluginInterface.PluginInterfaceTesting;
 import io.supertokens.storageLayer.StorageLayer;
 import io.supertokens.test.httpRequest.HttpRequestForTesting;
@@ -103,6 +104,9 @@ public static void reset() {
         PluginInterfaceTesting.isTesting = true;
         Main.makeConsolePrintSilent = true;
         String installDir = "../";
+        if (!new File(installDir + ".testEnvRunning").exists())
+            throw new QuitProgramException(
+                    "Testing environment is not running! Run the startTestingEnv script to start it.");
         try {
             // if the default config is not the same as the current config, we must reset the storage layer
             Path ogConfig = new File(installDir + "temp/config.yaml").toPath();

From 63bc059e8cfec57b592de73a2e713e68dc050a6e Mon Sep 17 00:00:00 2001
From: Jeremy E <34139712+JeremyEastham@users.noreply.github.com>
Date: Sat, 23 Apr 2022 04:13:20 -0500
Subject: [PATCH 09/12] Rename `startTestingEnv` script to `startTestEnv`

---
 .circleci/doTests.sh                         |  2 +-
 .github/workflows/tests.yml                  |  2 +-
 CONTRIBUTING.md                              | 52 ++++++++++++++------
 src/test/java/io/supertokens/test/Utils.java |  2 +-
 4 files changed, 41 insertions(+), 17 deletions(-)

diff --git a/.circleci/doTests.sh b/.circleci/doTests.sh
index 075c625ea..89d79dfce 100755
--- a/.circleci/doTests.sh
+++ b/.circleci/doTests.sh
@@ -144,7 +144,7 @@ do
         fi
         cd ../
         echo $SUPERTOKENS_API_KEY > apiPassword
-        ./startTestingEnv --cicd
+        ./startTestEnv --cicd
 
         if [[ $? -ne 0 ]]
         then
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index f0160e94f..72ae02a61 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -34,4 +34,4 @@ jobs:
       - name: Copying current supertokens-core branch into supertokens-root
         run: cd ../supertokens-root && rm -rf ./supertokens-core && cp -r ../supertokens-core ./
       - name: Building and running tests
-        run: cd ../supertokens-root && ./startTestingEnv
\ No newline at end of file
+        run: cd ../supertokens-root && ./startTestEnv --cicd
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index efb07bf5e..dbe3aeca9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -95,31 +95,53 @@ Please ask as many questions as you need, either directly in the issue or on [Di
         - Check the repository branches by clicking on the links listed above, click the branch tab to view all the available versions
     - Add your GitHub `username` separated by a ',' after `core,master` in  `modules.txt`
     - If, for example, your GitHub `username` is `helloworld` then modules.txt should look like:
-      ```
-      // put module name like module name,branch name,github username(if contributing with a forked repository) and then call ./loadModules script        
-      core,master,helloworld
-      plugin-interface,master
-      sqlite-plugin,master
-      ```
+        ```
+        // put module name like module name,branch name,github username(if contributing with a forked repository) and then call ./loadModules script        
+        core,master,helloworld
+        plugin-interface,master
+        sqlite-plugin,master
+        ```
 5. Run `./loadModules` to clone the required repositories
 6. Open `supertokens-root` in your IDE ([IntelliJ IDEA][intellij] is recommended)
 7. After gradle has imported all the dependencies you can start modifying the code
 
-## Testing
-
-### Running All Tests ([IntelliJ IDEA][intellij])
-1. Make sure that the `Start Testing Environment` run configuration and `./startTestingEnv` are not running
+## Developing With IntelliJ IDEA
+
+### Run Configurations
+![run configurations menu][image-run-configurations]
+- Several Run Configurations are available to run `supertokens-root` scripts
+    - **Lint:** `./gradlew spotlessApply`
+        - Run this configuration before committing
+    - **Run Core:** `./runCore`
+    - **Run All Tests:** `./startTestEnv`
+    - **Start Testing Environment:** `./startTestEnv --wait`
+        - Run this configuration when running individual tests
+    - **Load Modules:** `./loadModules`
+
+### Running All Tests
+1. Make sure that none of these are running:
+    - The `Start Testing Environment` run configuration
+    - The `Run All Tests` run configuration
+    - The `./startTestEnv` script
 2. Run the `Run All Tests` run configuration
 
-### Running Single Tests ([IntelliJ IDEA][intellij])
+### Running Single Tests
 1. Run the `Start Testing Environment` run configuration
 2. Wait for it to print `Test environment running...`
 3. Leave this script running in the terminal
 4. Click the Play button next to the test(s) that you want to run
+5. Tests can be debugged with breakpoints
+
+### Running the Core
+1. Edit `supertokens-root/supertokens-core/devConfig.yaml`
+2. Run the `Run Core` run configuration
+3. Breakpoints are **not supported** at this time
+
+## Developing Without IntelliJ IDEA
 
 ### Running All Tests (Manually)
 1. Navigate to the `supertokens-root` repository
-2. Run `./startTestingEnv`
+2. Run `./startTestEnv`
 3. If all tests pass the terminal should display
    - Core Tests:  
      ![core tests passing][image-core-tests-passing]
@@ -127,7 +149,7 @@ Please ask as many questions as you need, either directly in the issue or on [Di
      ![plugin tests passing][image-plugin-tests-passing]
 
 ### Running All Tests (GitHub Actions)
-1. Go to the supertokens-core repo on GitHub (or your forked version of it)
+1. Go to the `supertokens-core` repo on GitHub (or your forked version of it)
 2. Navigate to the Actions tab
 3. Find the action named "Run tests" and navigate to it
 4. Click on the "Run workflow" button
@@ -206,4 +228,6 @@ SuperTokens is made possible by a passionate team and a strong community of deve
 
 [image-core-tests-passing]: https://github.com/supertokens/supertokens-logo/blob/master/images/core-tests-passing.png
 
-[image-plugin-tests-passing]: https://github.com/supertokens/supertokens-logo/blob/master/images/plugin-tests-passing.png
\ No newline at end of file
+[image-plugin-tests-passing]: https://github.com/supertokens/supertokens-logo/blob/master/images/plugin-tests-passing.png
+
+[image-run-configurations]: https://github.com/supertokens/supertokens-logo/blob/master/images/supertokens-run-configurations.png
\ No newline at end of file
diff --git a/src/test/java/io/supertokens/test/Utils.java b/src/test/java/io/supertokens/test/Utils.java
index 11b6f7559..9ab8f815a 100644
--- a/src/test/java/io/supertokens/test/Utils.java
+++ b/src/test/java/io/supertokens/test/Utils.java
@@ -106,7 +106,7 @@ public static void reset() {
         String installDir = "../";
         if (!new File(installDir + ".testEnvRunning").exists())
             throw new QuitProgramException(
-                    "Testing environment is not running! Run the startTestingEnv script to start it.");
+                    "Testing environment is not running! Run the startTestEnv script to start it.");
         try {
             // if the default config is not the same as the current config, we must reset the storage layer
             Path ogConfig = new File(installDir + "temp/config.yaml").toPath();

From 5f653d28b3b040882d9df21c050f2642e48b6687 Mon Sep 17 00:00:00 2001
From: Jeremy E <34139712+JeremyEastham@users.noreply.github.com>
Date: Sun, 24 Apr 2022 18:49:08 -0500
Subject: [PATCH 10/12] Update `CONTRIBUTING.md`

---
 CONTRIBUTING.md | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dbe3aeca9..7db5933be 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -109,14 +109,15 @@ Please ask as many questions as you need, either directly in the issue or on [Di
 
 ### Run Configurations
 ![run configurations menu][image-run-configurations]
-- Several Run Configurations are available to run `supertokens-root` scripts
-    - **Lint:** `./gradlew spotlessApply`
-        - Run this configuration before committing
-    - **Run Core:** `./runCore`
-    - **Run All Tests:** `./startTestEnv`
-    - **Start Testing Environment:** `./startTestEnv --wait`
-        - Run this configuration when running individual tests
-    - **Load Modules:** `./loadModules`
+
+Several Run Configurations are available to run `supertokens-root` scripts:
+- **Lint:** `./gradlew spotlessApply`
+    - Run this configuration before committing
+- **Run Core:** `./runCore`
+- **Run All Tests:** `./startTestEnv`
+- **Start Testing Environment:** `./startTestEnv --wait`
+    - Run this configuration when running individual tests
+- **Load Modules:** `./loadModules`
 
 ### Running All Tests
 1. Make sure that none of these are running:
@@ -127,7 +128,7 @@ Please ask as many questions as you need, either directly in the issue or on [Di
 
 ### Running Single Tests
 1. Run the `Start Testing Environment` run configuration
-2. Wait for it to print `Test environment running...`
+2. Wait for it to print `Test environment started!`
 3. Leave this script running in the terminal
 4. Click the Play button next to the test(s) that you want to run
 5. Tests can be debugged with breakpoints

From ed1fc7857c6c3e0f8d46b39c870ccce52bfe1121 Mon Sep 17 00:00:00 2001
From: Jeremy E <34139712+JeremyEastham@users.noreply.github.com>
Date: Wed, 27 Apr 2022 01:18:21 -0500
Subject: [PATCH 11/12] Update `CONTRIBUTING.md`

---
 CONTRIBUTING.md | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7db5933be..6ae2b5fe3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -140,7 +140,7 @@ Several Run Configurations are available to run `supertokens-root` scripts:
 
 ## Developing Without IntelliJ IDEA
 
-### Running All Tests (Manually)
+### Running All Tests (With Console)
 1. Navigate to the `supertokens-root` repository
 2. Run `./startTestEnv`
 3. If all tests pass the terminal should display
@@ -149,7 +149,7 @@ Several Run Configurations are available to run `supertokens-root` scripts:
    - Plugin Tests:  
      ![plugin tests passing][image-plugin-tests-passing]
 
-### Running All Tests (GitHub Actions)
+### Running All Tests (With GitHub Actions)
 1. Go to the `supertokens-core` repo on GitHub (or your forked version of it)
 2. Navigate to the Actions tab
 3. Find the action named "Run tests" and navigate to it
@@ -159,10 +159,8 @@ Several Run Configurations are available to run `supertokens-root` scripts:
     - **supertokens-plugin-interface repos branch name**: If the core version you are working on is compatible with a plugin-interface version that is not in the master branch, then set the correct branch name in this value
 6. Click on "Run workflow"
 
-## Running the Core (Manually)
-1. Run `startTestingEnv --wait` in a terminal, and keep it running
-2. Then open `supertokens-root` in another terminal and run `cp ./temp/config.yaml .`
-3. Then run `java -classpath "./supertokens-core/*:./supertokens-plugin-interface/*" io.supertokens.Main ./ DEV`. This will start the core to listen on `http://localhost:3567`
+## Running the Core (With Console)
+1. Run `runCore` in a terminal, and keep it running. This will start the core to listen on `http://localhost:3567`
 
 ## Pull Requests
 1. Before submitting a pull request make sure all tests have passed

From e59776618e9cd2c08f158df586a67762b3b538ad Mon Sep 17 00:00:00 2001
From: Jeremy E <34139712+JeremyEastham@users.noreply.github.com>
Date: Wed, 27 Apr 2022 01:18:57 -0500
Subject: [PATCH 12/12] Update config regexes in `Config.java`

---
 src/test/java/io/supertokens/test/Utils.java | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/test/java/io/supertokens/test/Utils.java b/src/test/java/io/supertokens/test/Utils.java
index 9ab8f815a..7b6e7d408 100644
--- a/src/test/java/io/supertokens/test/Utils.java
+++ b/src/test/java/io/supertokens/test/Utils.java
@@ -148,13 +148,13 @@ private static void replaceConfigValue(String regex, String newStr) throws IOExc
     }
 
     public static void commentConfigValue(String key) throws IOException {
-        String find = "\r?\n#?\\s*" + Pattern.quote(key) + ":.*\r?\n";
+        String find = "\r?\n\\s*#?\\s*" + Pattern.quote(key) + ":.*\r?\n";
         String replace = newLine + "# " + key + ":" + newLine;
         replaceConfigValue(find, replace);
     }
 
     public static void setValueInConfig(String key, String value) throws IOException {
-        String find = "\r?\n#?\\s*" + Pattern.quote(key) + ":.*\r?\n";
+        String find = "\r?\n\\s*#?\\s*" + Pattern.quote(key) + ":.*\r?\n";
         String replace = newLine + key + ": " + value + newLine;
         replaceConfigValue(find, replace);
     }