Changing the API of the network package to use ByteStrings instead of Strings
Hi all, Now when network-bytestring is merged into network, the next natural step would be to slowly deprecate the String based functions for sending and receiving data in favor of the ByteString based ones. This will necessarily be a long process, as lots of code depend on these functions. Still I'd like to figure out a long term plan for completely removing the String based functions from the API, or at least deprecating them. In the long run I'd prefer not to have a separate ByteString API (under Network.Socket.ByteString) but to actually change the type of e.g. recv in Network.Socket. This would make the API smaller, making it easier to maintain and easier to understand. If that's not feasible, I'd at least like to add DEPRECATED pragmas to the String based functions to encourage the use of the ByteString based ones. I see two basic approaches: 1. Warn people of the upcoming change e.g. 6 months in advance, and then just change the types as part of a HP release. Delete the *.ByteString modules. 2. Deprecate the String based functions using pragmas, slowly move people over to the ByteString based ones. When everyone has moved over, change the types of the original functions to also use ByteStrings. Slowly migrate people back to the old functions (that now have a different type). Delete the *.ByteString modules. To be honest, I don't think 2 will ever work. From experience, without a deadline, people wont move. Is 1 even possible/desirable? What would a more concrete plan look like? Johan
On Oct 31, 2010, at 11:38 AM, Johan Tibell wrote:
I see two basic approaches:
1. Warn people of the upcoming change e.g. 6 months in advance, and then just change the types as part of a HP release. Delete the *.ByteString modules.
2. Deprecate the String based functions using pragmas, slowly move people over to the ByteString based ones. When everyone has moved over, change the types of the original functions to also use ByteStrings. Slowly migrate people back to the old functions (that now have a different type). Delete the *.ByteString modules.
A slightly more involved, but perhaps less painful proposal: Add a Network.Socket.String (or Network.Socket.OldStrings, or..) module as soon as possible, which just exports the old functions. At some near-future point, deprecate the String based functions from Network.ByteString, and encourage people to move to the ByteString based functions. At some further future point, change original functions to the ByteString version. Finally, eventually delete both the *.ByteString modules and throw the String based functions (ideally now wrappers of the ByteString ones) into a separate network-oldstring-compat library. That's essentially the Exceptions/OldExceptions model, I think (maybe with a few more steps even), and that was about as smooth as a major API transition has been. Cheers, Sterl. P.S. Apologies if this is a double-send to anyone -- my mail client hiccuped.
On Sun, Oct 31, 2010 at 04:38:25PM +0100, Johan Tibell wrote:
1. Warn people of the upcoming change e.g. 6 months in advance, and then just change the types as part of a HP release. Delete the *.ByteString modules.
2. Deprecate the String based functions using pragmas, slowly move people over to the ByteString based ones. When everyone has moved over, change the types of the original functions to also use ByteStrings. Slowly migrate people back to the old functions (that now have a different type). Delete the *.ByteString modules.
To be honest, I don't think 2 will ever work. From experience, without a deadline, people wont move.
You can have an overlap period and also deadlines. e.g. if HP major releases are yearly, then this would work for people wanting to support 2 major releases at all times: HP 2011: Add Network.Socket.ByteString. People wishing to support 2 major versions use Network.Socket. HP 2012: Deprecate Network.Socket. People wishing to support 2 major versions use Network.Socket.ByteString. HP 2013: Make Network.Socket use ByteString. People wishing to support 2 major versions use Network.Socket.ByteString. HP 2014: Deprecate or remove Network.Socket.ByteString. People wishing to support 2 major versions use Network.Socket. For changing the behaviour of names (as opposed to adding new behaviour with new names) this does get quite drawn out, though. Another option would be to make a network-string package exporting Network.Socket.String, which depends on network and either reexports Network.Socket directly (for old versions) or wraps the ByteString functions (for new versions). Then people can make their code use network-string now (which also works with HP 2010), and migrate back to network once it's a major release or 2 old. Thanks Ian
Ian Lynagh
On Sun, Oct 31, 2010 at 04:38:25PM +0100, Johan Tibell wrote:
1. Warn people of the upcoming change e.g. 6 months in advance, and then just change the types as part of a HP release. Delete the *.ByteString modules.
2. Deprecate the String based functions using pragmas, slowly move people over to the ByteString based ones. When everyone has moved over, change the types of the original functions to also use ByteStrings. Slowly migrate people back to the old functions (that now have a different type). Delete the *.ByteString modules.
To be honest, I don't think 2 will ever work. From experience, without a deadline, people wont move.
You can have an overlap period and also deadlines. e.g. if HP major releases are yearly, then this would work for people wanting to support 2 major releases at all times:
HP 2011: Add Network.Socket.ByteString. People wishing to support 2 major versions use Network.Socket.
HP 2012: Deprecate Network.Socket. People wishing to support 2 major versions use Network.Socket.ByteString.
HP 2013: Make Network.Socket use ByteString. People wishing to support 2 major versions use Network.Socket.ByteString.
HP 2014: Deprecate or remove Network.Socket.ByteString. People wishing to support 2 major versions use Network.Socket.
Three years? Ouch. I'd vote for a "tough love" approach, namely: bump
the major version number of network, remove the String functions from
Network.Socket immediately, and move them to
Network.Socket.String. Rather than going through N deprecation cycles,
why not just get on with it, like ripping off a band-aid? There's no
reason old code couldn't continue to depend on network-2.*. And the
upgrade path for lazy maintainers or people who want to stay on String
is trivial.
At the very least I would opt for Johan's first approach, namely
deprecating the string functions with a 6-month deadline.
If packages are following the PVP properly they shouldn't be pulling in
network-3.* anyways. But of course, lots of projects probably use
unqualified "network" imports; maybe we could grab some numbers on how
many Hackage libs would break?
G
--
Gregory Collins
participants (4)
-
Gregory Collins -
Ian Lynagh -
Johan Tibell -
Sterling Clover