From 363daa2a244e44e9f0bdbd7482d4786d2b003c1a Mon Sep 17 00:00:00 2001
From: Brikaa <brikaaomar@gmail.com>
Date: Mon, 4 Oct 2021 21:35:13 +0200
Subject: [PATCH] Document limit_overrides, timeouts, provides and local
 testing

---
 docs/configuration.md    | 31 ++++++++++++++++++++++++++--
 packages/CONTRIBUTING.MD | 44 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 16a5df0..4c6601a 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -86,11 +86,11 @@ key: PISTON_MAX_PROCESS_COUNT
 default: 64
 ```
 
-Maximum number of processess allowed to to have open for a job.
+Maximum number of processes allowed to to have open for a job.
 
 Resists against exhausting the process table, causing a full system lockup.
 
-## Output Max Side
+## Output Max Size
 
 ```yaml
 key: PISTON_OUTPUT_MAX_SIZE
@@ -123,6 +123,19 @@ Maximum size for a singular file written to disk.
 
 Resists against large file writes to exhaust disk space.
 
+## Compile/Run timeouts
+```yaml
+key:
+  - PISTON_COMPILE_TIMEOUT
+default: 10000
+
+key:
+  - PISTON_RUN_TIMEOUT
+default: 3000
+```
+The maximum time that is allowed to be taken by a stage in milliseconds.
+Use -1 for unlimited time.
+
 ## Compile/Run memory limits
 
 ```yaml
@@ -154,3 +167,17 @@ default: 64
 ```
 
 Maximum number of jobs to run concurrently.
+
+## Limit overrides
+
+```yaml
+key: PISTON_LIMIT_OVERRIDES
+default: {}
+```
+
+Per-language overrides/exceptions for the each of `max_process_count`, `max_open_files`, `max_file_size`,
+`compile_memory_limit`, `run_memory_limit`, `compile_timeout`, `run_timeout`, `output_max_size`. Defined as follows:
+```
+PISTON_LIMIT_OVERRIDES={"c++":{"max_process_count":128}}
+```
+This will give `c++` a max_process_count of 128 regardless of the configuration.
diff --git a/packages/CONTRIBUTING.MD b/packages/CONTRIBUTING.MD
index b1ed6d3..53deda9 100644
--- a/packages/CONTRIBUTING.MD
+++ b/packages/CONTRIBUTING.MD
@@ -40,7 +40,7 @@ public class Test
 }
 ```
 
-8. Create a `metadata.json` file which contains metadata about the language and interpreter. This simply contains the language name, as in the folder name, the version as in the folder name, aliases that can be used to call this package, and finally a dependencies map.
+8. Create a `metadata.json` file which contains metadata about the language and interpreter. This simply contains the language name, as in the folder name, the version as in the folder name, aliases that can be used to call this package, limit overrides (if any) that can be used to override the default constraints and finally a dependencies map.
 The dependencies map contains the keys as language names, and the values as semver selectors for packages.
 ```json
 {
@@ -50,9 +50,49 @@ The dependencies map contains the keys as language names, and the values as semv
     "aliases": ["deno-ts", "deno-js"]
 }
 ```
+If the interpreter/compiler provides multiple languages, then the provides property should be used:
+```json
+{
+    "language": "dotnet",
+    "version": "5.0.201",
+    "provides": [
+        {
+            "language": "basic.net",
+            "aliases": [
+                "basic",
+                "visual-basic",
+                "visual-basic.net",
+                "vb",
+                "vb.net",
+                "vb-dotnet",
+                "dotnet-vb",
+                "basic-dotnet",
+                "dotnet-basic"
+            ],
+            "limit_overrides": { "max_process_count": 128 }
+        },
+        {
+            "language": "fsi",
+            "aliases": [
+                "fsx",
+                "fsharp-interactive",
+                "f#-interactive",
+                "dotnet-fsi",
+                "fsi-dotnet",
+                "fsi.net"
+            ]
+        }
+    ]
+}
+```
 
 9. Test your package builds with running `make [language]-[version].pkg.tar.gz`.
-If it all goes to plan, you should have a file named `[language]-[version].pkg.tar.gz`, in this case your good to go!
+If it all goes to plan, you should have a file named `[language]-[version].pkg.tar.gz`, in this case you're good to go, albeit it is preferable to test the package locally as follows
+```shell
+./piston build-pkg [package] [version]
+./piston ppman install [package]=[version]
+./piston run [package] -l [version] packages/[package]/[version]/test.*
+```
 
 10. Commit your changes, using message format of `pkg([language]-[version]): Added [language] [version]`
 Any additional commits regarding this package should start with `pkg([language]-[version]): `