Added examples / explanation of JSON file format

JSON.md

@@ -0,0 +1,178 @@
+# CFEngine Build JSON file format
+
+The CFEngine Build website and tooling relies on JSON files for different purposes;
+
+- The project file generated by running `cfbs` in your
+- The index of all available modules which is available on GitHub
+- A cfbs.json file with necessary metadata for adding a module using URL (not from index)
+
+All these 3 share 1 standard format, commonly called `cfbs.json`.
+
+(There is also [`versions.json`](https://github.com/cfengine/cfbs-index/blob/master/versions.json), but this specification is not about that file).
+
+## Keys
+
+`index`: URL, relative path, or inline dictionary.
+Used by `cfbs add` and `cfbs search`, when index key is present in `cfbs.json` in the current working directory.
+When adding a module by URL, which has a cfbs.json inside of it, the index in that file should be ignored.
+
+## Examples
+
+### New project
+
+Starting in an empty folder you can create a new project with the `init` command:
+
+```
+cfbs init
+```
+
+Which creates a file like this:
+
+```json
+{
+ "name": "Example",
+ "description": "Example description",
+ "type": "policy-set",
+ "build": []
+}
+```
+
+### Adding a module
+
+Continuing from the previous project, we can add a module:
+
+```
+cfbs add mpf
+```
+
+Which results in:
+
+```json
+{
+ "name": "Example",
+ "description": "Example description",
+ "type": "policy-set",
+ "build": [
+ {
+ "name": "masterfiles",
+ "description": "Official CFEngine Masterfiles Policy Framework (MPF)",
+ "tags": ["official", "base", "supported"],
+ "repo": "https://github.com/cfengine/masterfiles",
+ "by": "https://github.com/cfengine",
+ "version": "0.1.1",
+ "commit": "5c7dc5b43088e259a94de4e5a9f17c0ce9781a0f",
+ "steps": [
+ "run ./autogen.sh",
+ "delete ./autogen.sh",
+ "run ./cfbs/cleanup.sh",
+ "delete ./cfbs/cleanup.sh",
+ "copy ./ ./"
+ ],
+ "added_by": "cfbs add"
+ }
+ ]
+}
+```
+
+## Alternate index
+
+You can start a project with an alternate index:
+
+```
+cfbs init --index blah
+```
+
+```json
+{
+ "name": "Example",
+ "description": "Example description",
+ "type": "policy-set",
+ "index": "blah",
+ "build": []
+}
+```
+
+`blah` can be a URL or a relative file path (inside project).
+
+## Index file
+
+The index file used by `cfbs` also follows the same format:
+
+```json
+{
+ "name": "Official CFEngine Build Index (default)",
+ "description": "File used by tooling and website to find modules",
+ "type": "index",
+ "index": {
+ "masterfiles": {
+ "description": "Official CFEngine Masterfiles Policy Framework (MPF)",
+ "tags": ["official", "base", "supported"],
+ "repo": "https://github.com/cfengine/masterfiles",
+ "by": "https://github.com/cfengine",
+ "version": "0.1.1",
+ "commit": "5c7dc5b43088e259a94de4e5a9f17c0ce9781a0f",
+ "steps": [
+ "run ./autogen.sh",
+ "delete ./autogen.sh",
+ "run ./cfbs/cleanup.sh",
+ "delete ./cfbs/cleanup.sh",
+ "copy ./ ./"
+ ]
+ }
+ }
+}
+```
+
+(Only showing 1 module here, the real file has many more).
+
+Note that it is reusing the `index` key, but this time with a dictionary (inline index).
+
+## A separate repo which provides modules
+
+If you put your modules in a repo and don't have them in the index (yet), you can use the `provides` key:
+
+```json
+{
+ "name": "Example module in separate repo",
+ "description": "Example description",
+ "type": "module",
+ "provides": {
+ "example-module": {
+ "name": "example-module",
+ "description": "Just an example",
+ "tags": ["local"],
+ "version": "1.0.0",
+ "dependencies": ["autorun"],
+ "steps": ["copy ./test.cf services/autorun/test.cf"],
+ "added_by": "cfbs add"
+ }
+ }
+}
+```
+
+## Adding a module from repo URL
+
+```
+cfbs init && cfbs add https://github.com/cfengine/some-repo
+```
+
+```json
+{
+ "name": "Example",
+ "description": "Example description",
+ "type": "policy-set",
+ "build": [
+ {
+ "name": "example-module",
+ "description": "Just an example",
+ "tags": ["local"],
+ "repo": "https://github.com/cfengine/some-repo",
+ "version": "1.0.0",
+ "commit": "be3bc015f6a19e945bb7a9fa0ed78c97e2cecf61",
+ "dependencies": ["autorun"],
+ "steps": ["copy ./test.cf services/autorun/test.cf"],
+ "added_by": "cfbs add"
+ }
+ ]
+}
+```