From f660942459f8b369db7fed06b03ef951c88f031c Mon Sep 17 00:00:00 2001 From: Ole Herman Schumacher Elgesem Date: Fri, 12 Jan 2024 17:18:04 +0100 Subject: [PATCH 1/2] JSON.md: Added a note on reproducibility and backwards compatibility of cfbs Signed-off-by: Ole Herman Schumacher Elgesem --- JSON.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/JSON.md b/JSON.md index fde92b04..df3043ac 100644 --- a/JSON.md +++ b/JSON.md @@ -263,6 +263,25 @@ Unless otherwise noted, all steps are run inside the module's folder (`out/steps * Source is relative to module directory and target is relative to `out/masterfiles`. * In most cases, the build step should be: `input ./input.json def.json` +### A note on reproducibility and backwards compatibility + +As mentioned in [the README](./README.md), our main focus when it comes to reproducibility and backwards compatibility of `cfbs` is the `cfbs build` command. +(This also extends to `cfbs download` since that is the first part of `cfbs build`). +Anyone who has a working CFEngine Build project, should expect it to keep working (keep building) after upgrading their hub or their version of cfbs. +Ideally, the resulting policy set tarball should be bit-by-bit identical (reproducible), including metadata, so that checksums are easy to compare. +We are not there yet, see this ticket for more progress in this area: + +https://northerntech.atlassian.net/browse/CFE-4102 + +Conversely, for other commands, we might choose to make changes where we think it's a good idea (for example for the user experience, performance or security of the tool). +Some examples of where you might experience changes are: + +* The commands which edit `cfbs.json`, or other files, might produce different JSON files in future versions. + (`cfbs init`, `cfbs add`, etc.). +* We might add more strict validation, so `cfbs validate` and `cfbs status` could start giving warnings or errors after upgrading to a new version. +* The interactive prompts might be drastically changed to help the user experience and give more advanced options. + Don't rely on the exact prompts, order of prompts, or output of `cfbs init`, `cfbs add`, etc. + ## Examples ### New project From b679a207319d704b73c88f385633fdcc29992796 Mon Sep 17 00:00:00 2001 From: Ole Herman Schumacher Elgesem Date: Fri, 12 Jan 2024 17:18:30 +0100 Subject: [PATCH 2/2] README.md: Added a note about future validation changes to cfbs validate Signed-off-by: Ole Herman Schumacher Elgesem --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 95a428b8..80835783 100644 --- a/README.md +++ b/README.md @@ -289,6 +289,7 @@ These commands are intended to be run as part of build systems / deployment pipe Expected usage is to run `cfbs get-input` to get the JSON, and then fill out the response part and run `cfbs set-input`. * `cfbs validate`: Used to validate the [index JSON file](https://github.com/cfengine/build-index/blob/master/cfbs.json). May be expanded to validate other files and formats in the future. + **Note:** If you use `cfbs validate` as part of your automation, scripts, and build systems, be aware that we might add more strict validation rules in the future, so be prepared to sometimes have it fail after upgrading the version of cfbs. They don't have interactive prompts, you can expect fewer changes to them, and backwards compatibility is much more important than with the interactive commands above.