Skip to content

[RFC] Add document detailing Cascade's backwards compatibility commitments post 1.0 #142

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

[RFC] Add document detailing Cascade's backwards compatibility commitments post 1.0 #142

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
42 changes: 42 additions & 0 deletions backwards_compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Cascade backwards compatibility
Cascade follows semantic versioning (https://semver.org/). This means that all
changes in a major version are considered backwards compatible. An increment
Comment on lines +2 to +3
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"This means that all changes in a major version are considered backwards compatible." -> "This means that all changes in a major version are compatible with each other" may be a bit clearer. Though I am not fully sold on my suggested change.

of the major version signifies a breaking change, an increment of the the minor
version signifies a backwards compatible addition of functionality, and an
increment of the patch number indicates bug fixes.

Changes to the following will be considered breaking backwards compatibiliy
for Cascade:

1. Any change to the signatures of existing public API elements in the library
portion of Cascade.
2. Any user visible change to the usage of command line arguments on casc.
3. Any Cascade policy that previously compiled correctly, produced valid CIL
that compiled correctly, and was in line with the behavior specified in the
Cascade documentation, unless a warning was displayed on that policy for the
entirety of the major version.
Comment on lines +14 to +17
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may be worthwhile to explicitly point out consistency for the produced CIL. When we were talking about the implicit "this" stuff we brought up a potential issue that we may get into a situation where a given policy module does not change but something in an interface it calls does. The module still compiles and produces valid CIL but not the originally intended CIL. In that example it was a change in the policy itself but if we do something that would produce similar results in the compiler itself that would also be a breaking change.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some of the below points partially contradict what I have here. I'm going to leave the comment because I do want to talk a bit about this.


Changes to the following will *NOT* be considered backwards compatibility
breaking changes for Cascade:

1. The addition of new public API elements (increment minor version)
2. The addition of new flags and options to casc (increment minor version)
3. The addition of new binaries (eg audit2cascade)
4. Modification to anything that was explicitly declared to be unstable in the
documentation (for example, if Cascade begins publishing a new binary, it may
have a period of unstability). Such exceptions will be clearly documented.
5. As we add new functionality, policy that did not previously compile may
start to compile.
6. If a policy compiled to invalid CIL, that is considered a Cascade bug. No
guarantees are made about preserving any backwards compatibilty around such
policy.
7. If a policy display a warning message which indicates that it may change,
changing that policy syntax will not be considered a breaking change. However,
if a major version was published without such a warning at some point, then the
change becomes a breaking change.
8. The addition of new compiler *warnings* to previously compiling policy is
not considered a breaking change.
9. Fixing compilation to valid but incorrect behavior will not be considered a
breaking change. For example, policy that compiled but omitted certain policy
rules may begin to output those rules in a future minor version. However, if
those new rules produce invalid CIL, that is a Cascade bug.