Coding standard: Deprecation rules

[tautschnig]

Thus far, we operated an informal deprecation policy. This codifies our
informal six-months rule.

This has a soft dependency on #4423 as the SINCE macro will only be available once that PR is merged.

• Each commit message has a non-empty body, explaining why the change was made.
• n/a Methods or procedures I have added are documented, following the guidelines provided in CODING_STANDARD.md.
• n/a The feature or user visible behaviour I have added or modified has been documented in the User Guide in doc/cprover-manual/
• n/a Regression or unit tests are included, or existing tests cover the modified code (in this case I have detailed which ones those are in the commit message).
• n/a My commit message includes data points confirming performance improvements (if claimed).
• My PR is restricted to a single feature or bugfix.
• n/a White-space or formatting changes outside the feature-related changed lines are in commits of their own.

[peterschrammel]

What's the scope of this rule? code seems too general to be a useful guidance.

[tautschnig]

code seems too general to be a useful guidance.

Good point - would "API" work? Or "public API?"

[peterschrammel]

What that be anything declared in a header file?

[tautschnig]

What that be anything declared in a header file?

In C++ it's really hard to pin down what is/isn't (part of) an API. I'd say anything that is meant to be used outside a module, where I would consider as "module" a directory.

[kroening]

I would perhaps add "or marked as deprecated".

[allredj]

✔️
Passed Diffblue compatibility checks (cbmc commit: b39726b).
Build URL: https://travis-ci.com/diffblue/test-gen/builds/105538719

[peterschrammel]

In C++ it's really hard to pin down what is/isn't (part of) an API.

That's not a property of C++, but of how we structure the code base.

meant to be used outside a module

Please add this definition to make it a bit clearer.

[tautschnig]

I have made some changes to the wording and added a second commit that codifies the idea of an interface.

[tautschnig]

That's not a property of C++, but of how we structure the code base.

We might discuss this a bit more, but that's likely more efficient over drinks than via GitHub...

[allredj]

✔️
Passed Diffblue compatibility checks (cbmc commit: f3a8371).
Build URL: https://travis-ci.com/diffblue/test-gen/builds/105539964

[martin-cs]

How does this fit with the release cycle? If we are deprecating user-facing functionality should we give them at least one release where it has a warning?

[tautschnig]

How does this fit with the release cycle?

I think we were aiming for one release per quarter, so we should have one or two releases in between. But I'm not sure we are currently on track for quarterly releases...

[martin-cs]

On Sat, 2019-03-23 at 15:20 -0700, Michael Tautschnig wrote: > How does this fit with the release cycle? I think we were aiming for one release per quarter, so we should have one or two releases in between. But I'm not sure we are currently on track for quarterly releases...

This seems reasonable. I guess there is a bit of a difference between internal APIs used for tools based on CPROVER and user-facing features.