Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENT-11175: Rewrote the intro to be more clear about different types of projects #178

Merged
merged 2 commits into from
Jan 9, 2024
Merged

ENT-11175: Rewrote the intro to be more clear about different types of projects #178

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a05166
JSON.md: Rewrote the intro to be more clear about different types of …
olehermanse Jan 9, 2024
bba2de1
Added suggestions from @craigcomstock's code review
olehermanse Jan 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 20 additions & 6 deletions JSON.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,28 @@
# 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`.
The type of a project is specified in a top-level `type` key in `cfbs.json`.
There are 3 types of projects:

(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 top-level `build` key to specify which modules to use in `cfbs build`.
* The index of all available modules for `cfbs add <module-name>` 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 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`.

## The process of building modules from a project into a policy set

Expand Down
Loading