Establish proposal procedure #196

CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - `is_infinity`
     - `nan`
 
+### Changed
+- Added `proposals` folder for experimental processes. Experimental processes are not covered by the CHANGELOG!
+    - Moved the experimental processes `aggregate_spatial_binary`, `reduce_dimension_binary` and `run_udf_externally` to the proposals.
+
 ### Fixed
 - Clarify how the parameters passed to the overlap resolver correspond to the data cubes. [#184](https://github.com/Open-EO/openeo-processes/issues/184)
 - Improve and clarify specifications for `is_nan`, `is_nodata`, `is_valid`. [#189](https://github.com/Open-EO/openeo-processes/issues/189)

README.md

@@ -6,7 +6,9 @@ openEO develops interoperable processes for big Earth observation cloud processi
 
 ## Versions / Branches
 
-The [master branch](https://github.com/Open-EO/openeo-processes/tree/master) is the 'stable' version of the openEO processes specification. The latest release is version **1.0.0**. The [draft branch](https://github.com/Open-EO/openeo-processes/tree/draft) is where active development takes place.
+The [master branch](https://github.com/Open-EO/openeo-processes/tree/master) is the 'stable' version of the openEO processes specification. Exception is the [`proposals`](proposals/) folder, which provides experimental new processes currently under discussion. They may still change, but everyone is encouraged to implement them and give feedback.
+
+The latest release is version **1.0.0**. The [draft branch](https://github.com/Open-EO/openeo-processes/tree/draft) is where active development takes place. PRs should be made against the draft branch.
 
 | Version / Branch                                             | Status                    | openEO API versions |
 | ------------------------------------------------------------ | ------------------------- | ------------------- |
@@ -25,7 +27,8 @@ See also the [changelog](CHANGELOG.md) for the changes between versions and the
 
 This repository contains a set of files formally describing the openEO Processes:
 
-* The `*.json` files provide the process specifications as defined by the openEO API.
+* The `*.json` files provide the stable process specifications as defined by openEO. New processes need at least two implementations.
+* The `*.json` files in the [`proposals`](proposals/) folder provide proposed new process specifications that are only implemented by one organization and may still change. Everyone is encouraged to base their work on the proposals and give feedback so that eventually the processes evolve into stable proces specifications.
 * [subtype-schemas.json](meta/subtype-schemas.json) in the `meta` folder defines common data types (`subtype`s) for JSON Schema used in openEO processes.
 * The [`examples`](examples/) folder contains some useful examples that the processes link to. All of these are non-binding additions.
 * The [`tests`](tests/) folder can be used to test the process specification for validity and and consistent "style". It also allows to render the processes in a web browser.

aggregate_spatial_window.json → proposals/aggregate_spatial_window.json

@@ -6,6 +6,7 @@
         "cubes",
         "aggregate & resample"
     ],
+    "experimental": true,
     "parameters": [
         {
             "name": "data",

tests/package.json

@@ -30,7 +30,7 @@
   },
   "scripts": {
     "test": "jest",
-    "generate": "concat-json-files \"../*.json\" -t \"processes.json\"",
+    "generate": "concat-json-files \"../{*,proposals/*}.json\" -t \"processes.json\"",
     "render": "npm run generate && http-server -p 9876 -o docs.html -c-1"
   }
 }

tests/processes.test.js

@@ -13,24 +13,30 @@ beforeAll(async () => {
 	jsv = await getAjv();
 });
 
-var processes = [];
-const files = glob.sync("../*.json", {realpath: true});
-files.forEach(file => {
+var loader = (file, proposal = false) => {
 	try {
 		var fileContent = fs.readFileSync(file);
 		// Check JSON structure for faults
 		var p = JSON.parse(fileContent);
 
 		// Prepare for tests
-		processes.push([file, p, fileContent.toString()]);
+		processes.push([file, p, fileContent.toString(), proposal]);
 	} catch(err) {
-		processes.push([file, {}, ""]);
+		processes.push([file, {}, "", proposal]);
 		console.error(err);
 		expect(err).toBeUndefined();
 	}
-});
+};
+
+var processes = [];
+
+const files = glob.sync("../*.json", {realpath: true});
+files.forEach(file => loader(file));
+
+const proposals = glob.sync("../proposals/*.json", {realpath: true});
+proposals.forEach(file => loader(file, true));
 
-describe.each(processes)("%s", (file, p, fileContent) => {
+describe.each(processes)("%s", (file, p, fileContent, proposal) => {
 
 	test("File / JSON", () => {
 		const ext = path.extname(file);
@@ -77,7 +83,7 @@ describe.each(processes)("%s", (file, p, fileContent) => {
 	});
 
 	test("Flags", () => {
-		checkFlags(p);
+		checkFlags(p, proposal);
 	});
 
 	test("Parameters", () => {
@@ -204,15 +210,20 @@ describe.each(processes)("%s", (file, p, fileContent) => {
 	}
 });
 
-function checkFlags(p) {
+function checkFlags(p, proposal = false) {
 	// deprecated
 	expect(typeof p.deprecated === 'undefined' || typeof p.deprecated === 'boolean').toBeTruthy();
 	// lint: don't specify defaults
 	expect(typeof p.deprecated === 'undefined' || p.deprecated === true).toBeTruthy();
-	// experimental
-	expect(typeof p.experimental === 'undefined' || typeof p.experimental === 'boolean').toBeTruthy();
-	// lint: don't specify defaults
-	expect(typeof p.experimental === 'undefined' || p.experimental === true).toBeTruthy();
+	if (proposal) {
+		// experimental must be true for proposals
+		expect(p.experimental).toBe(true);
+	}
+	else {
+		// experimental must not be false for stable
+		// lint: don't specify defaults, so false should not be set explicitly
+		expect(p.experimental).toBeUndefined();
+	}
 }
 
 function checkParam(param, p, checkCbParams = true) {

tests/testHelpers.js

@@ -27,7 +27,7 @@ for(let i in words) {
 	spellcheck.spellcheck.addWord(words[i]);
 }
 // Add the process IDs to the word list
-const files = glob.sync("../*.json", {realpath: true});
+const files = glob.sync("../{*,proposals/*}.json", {realpath: true});
 for(let i in files) {
 	spellcheck.spellcheck.addWord(path.basename(files[i], path.extname(files[i])));
 }