-
Notifications
You must be signed in to change notification settings - Fork 4
[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.
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
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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 | ||
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
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. |
There was a problem hiding this comment.
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.