-
Notifications
You must be signed in to change notification settings - Fork 696
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
Cabal backwards-compatibility guidelines proposal #3573
Comments
I would like for
|
OK, I modified the text to mention this. Though I wonder now if we shouldn't create "deprecation" tickets describing in detail how the interface changed and how to update code to use it. Only having one line is a bit restrictive. |
@ezyang this is about functions... and I guess it can mostly be applied to class methods as well... but what about changing |
I feel like we are screwed forever. Here are some observations:
I don't have any general guidance when you should do what. I try not to rename fields; e.g. #3597 sucks but I'd just not fix it. |
I think setup-depends should lift this burden from us. I think we don't need to worry about library BC if we require that all packages with a custom Setup have an upper bound on a released version of Cabal (with an implict |
I'd say, Cabal is just a library. Use version bounds. |
This is a proposal for some backwards-compatibility guidelines. It is incomplete so please make me more complete.
So you've decided you need to change the type of some function in the Cabal library, usually because you need some extra information, etc. The normal workflow in a Haskell project is to change the signature, and then keep editing files to adjust to the new signature until your project compiles again.
If the function in question is exported and part of the public API, here's what you should do instead:
{-# DEPRECATED #-}
tag what the new function name is called, what the deprecated function does in relation to it, how to change to use the new function, and when this function will be removed. The default policy is that functions are removed the next release after deprecation. (Note that deprecation descriptions don't support multiple lines, so you'll have to keep everything on the same line) Here is an example:changelog
describing what function you deprecated and what the new form is.If you think no one is using a function, get a copy of Hackage https://stackoverflow.com/questions/14758423/how-can-one-make-a-private-copy-of-hackage and grep for the identifier. If you can demonstrate there are no uses, go ahead and change the type but make sure you still add a changelog entry.
The text was updated successfully, but these errors were encountered: