From 6a051664f0819cc29a20207d9e80a9fd45577c8c Mon Sep 17 00:00:00 2001 From: Ole Herman Schumacher Elgesem Date: Tue, 9 Jan 2024 17:08:47 +0100 Subject: [PATCH 1/2] JSON.md: Rewrote the intro to be more clear about different types of projects Ticket: ENT-11175 Signed-off-by: Ole Herman Schumacher Elgesem --- JSON.md | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/JSON.md b/JSON.md index 51d92c27..d42a4d61 100644 --- a/JSON.md +++ b/JSON.md @@ -1,14 +1,27 @@ # CFEngine Build JSON file format -The CFEngine Build website and tooling relies on JSON files for different purposes; +The `cfbs` command line tool uses `cfbs.json` configuration files. +We call the folder / git repo which has a `cfbs.json` file (and optionally other files and folders) a _project_, and the end result after combining modules in a project into policy a _policy set_. +The _policy set_ is what you deploy to your CFEngine hub / policy server, in `/var/cfengine/masterfiles`. -* The project file (`cfbs.json`) generated by running `cfbs init` when you start a new project -* 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) +See the [README](https://github.com/cfengine/cfbs/blob/master/README.md) for general documentation on the `cfbs` tool and its commands. +This file is specifically about the `cfbs.json` file format, it should serve as detailed and useful information for more advanced users who are making their own modules or contributing to CFEngine Build. -All these 3 share 1 standard format, commonly called `cfbs.json`. +There are 3 types of `cfbs.json` files: -(There is also [`versions.json`](https://github.com/cfengine/cfbs-index/blob/master/versions.json), but this specification is not about that file). +* For building a policy set you create a project with type `policy-set`. + This is the default when running `cfbs init`, and what most users encounter when first using the tool and CFEngine. + You then need to use the `build` key to specify which modules to use in `cfbs build`. +* The index of all available modules for `cfbs add ` has type `index`. + The available modules must be in a dictionary in the `index` field. + By default, [this index available GitHub](https://github.com/cfengine/build-index/blob/master/cfbs.json) is used. +* When developing your own reusable modules to use in other projects, `module` type is used. + +When `cfbs` is using the default index and when we build the [build.cfengine.com](https://build.cfengine.com) website, we use a separate [`versions.json`](https://github.com/cfengine/build-index/blob/master/versions.json) file to keep track of all the versions of modules, their tarballs and checksums. +When contributors edit the index ([like this](https://github.com/cfengine/build-index/pull/465/files)), an automated PR is generated to make the appropriate edit to `versions.json` ([like this](https://github.com/cfengine/build-index/pull/466/files)), (after downloading and uploading the module), so users don't have to `versions.json` manually. + +Note that while the 3 types above add some requirements to which fields you must use, the file format and `cfbs` tool is quite flexible. +It is for example entirely possible, and encouraged, to use the `build` field and `cfbs build` command to build and test a policy set, while you are working on a module in a project with type `module`. ## The process of building modules from a project into a policy set From bba2de117cacf85f8c19f30e39b8de459d3ee1f6 Mon Sep 17 00:00:00 2001 From: Ole Herman Schumacher Elgesem <4048546+olehermanse@users.noreply.github.com> Date: Tue, 9 Jan 2024 19:11:40 +0100 Subject: [PATCH 2/2] Added suggestions from @craigcomstock's code review Co-authored-by: Craig Comstock --- JSON.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/JSON.md b/JSON.md index d42a4d61..58aa1bfe 100644 --- a/JSON.md +++ b/JSON.md @@ -7,18 +7,19 @@ The _policy set_ is what you deploy to your CFEngine hub / policy server, in `/v See the [README](https://github.com/cfengine/cfbs/blob/master/README.md) for general documentation on the `cfbs` tool and its commands. This file is specifically about the `cfbs.json` file format, it should serve as detailed and useful information for more advanced users who are making their own modules or contributing to CFEngine Build. -There are 3 types of `cfbs.json` files: +The type of a project is specified in a top-level `type` key in `cfbs.json`. +There are 3 types of projects: * For building a policy set you create a project with type `policy-set`. This is the default when running `cfbs init`, and what most users encounter when first using the tool and CFEngine. - You then need to use the `build` key to specify which modules to use in `cfbs build`. + You then need to use the top-level `build` key to specify which modules to use in `cfbs build`. * The index of all available modules for `cfbs add ` has type `index`. The available modules must be in a dictionary in the `index` field. By default, [this index available GitHub](https://github.com/cfengine/build-index/blob/master/cfbs.json) is used. * When developing your own reusable modules to use in other projects, `module` type is used. When `cfbs` is using the default index and when we build the [build.cfengine.com](https://build.cfengine.com) website, we use a separate [`versions.json`](https://github.com/cfengine/build-index/blob/master/versions.json) file to keep track of all the versions of modules, their tarballs and checksums. -When contributors edit the index ([like this](https://github.com/cfengine/build-index/pull/465/files)), an automated PR is generated to make the appropriate edit to `versions.json` ([like this](https://github.com/cfengine/build-index/pull/466/files)), (after downloading and uploading the module), so users don't have to `versions.json` manually. +When contributors edit the index ([like this](https://github.com/cfengine/build-index/pull/465/files)), an automated PR is generated to make the appropriate edit to `versions.json` ([like this](https://github.com/cfengine/build-index/pull/466/files)), (after downloading and uploading the module), so users don't have to update `versions.json` manually. Note that while the 3 types above add some requirements to which fields you must use, the file format and `cfbs` tool is quite flexible. It is for example entirely possible, and encouraged, to use the `build` field and `cfbs build` command to build and test a policy set, while you are working on a module in a project with type `module`.