Merge pull request #184 from olehermanse/pretty

Added some notes about backwards compatibility and reproducibility to markdown docs

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

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.