Libraries/WhenToRewriteOrRename

There have been a few cases of major API changes / rewrites to famous old packages causing problems, including:

• QuickCheck 1 vs 2
• parsec 2 vs 3
• OpenGL
• Haxml 1.13,1.19

a similar opportunity is present with 'fgl', where the new maintainers are seeking to improve the code.

Below I try to summarise the pros and cons of calling the new rewrite/api 'fgl', in the hope we can identify a path that minimizes disruption to users.

---

A group of developers is planning to write a new graph library for Haskell.

• They maintain an existing package called 'fgl'.
• 'fgl' has a long history: http://web.engr.oregonstate.edu/~erwig/fgl/
• The new library will have different authors and a different API.
• They would like to call the new library 'fgl'.

It is a controversial step to write a new library and give it the same name as an existing, famous library. Let's look at the arguments.

Quoting Duncan Coutts on #haskell (with some formatting added): the critical issues are:

1. Is the new API in the spirit of the old?

2. Do you have the support of a) the previous maintainer and b) current users

3. Will the new implementation actually be better?

4. Will the transition be managed well?

Reasons to use the old name

• Considering the four points raised by Duncan, we believe that the first and third points are/will be met; we have plans to manage the transition and the point of the "technology preview" releases is to ensure 2. b). We have not, however, directly contacted Martin as yet.

• The new code will be better, and should be preferred. Using the name 'fgl' will ensure adoption.

• Rewrites are effective if the name is preserved. E.g. QuickCheck 2.

• It is the maintainer's right to modify APIs as they see fit.

• Keeping the old fgl around as a separate package, there is then no real incentive to change/upgrade.

• Relatively few packages use fgl. So damage is limited.

• It makes development by new users simpler by not fracturing the package-space (the "Which version of QuickCheck should I use?" problem).

• It decreases the maintainer workload as the same person or team will often be responsible for both packages.

• A lot of respected members of the Haskell community (e.g. Cale) do not like many aspects of the current API (and thus refuse to use it) and we're taking their points of view into account.

• The new version of the library is keeping the "spirit" of old fgl alive, but modernising the interface and providing new functionality (e.g. the ability to restrict the label types or use a custom Node type).

• There will be a full transition guide between the old and new versions (something that was lacking for packages like QuickCheck from what I could tell).

• Major version numbers exist for a reason: to denote breakage. We really need to educate developers to avoid having too lax or open-ended package dependencies.

Reasons not to use the name

• Code that depends on 'fgl' will break. There are 23 direct and 25 indirect dependencies on fgl. http://bifunctor.homelinux.net/~roel/cgi-bin/hackage-scripts/revdeps/fgl-5.4.2.2#direct

• • Rebuttal:

• • • Have contacted all maintainers of packages on Hackage which have packages without an upper bound on the version of fgl used; most have already gotten back to me saying they will release a bug-fix version to resolve this.

• • • With the Package_versioning_policy, people should always have upper bounds on their dependencies anyway.

• • • Until new fgl is stabilised, Hackage can set the default version of fgl to be < 6 (same as what happened with base-3 to base-4 transition, etc., thus any packages that do not have an upper bound will not be affected by cabal-install, etc.

• Doesn't matter if the old fgl is still around. If the new code is better, it will be adopted on its own merits (see e.g. bytestrings vs packedstring, vector vs uvector) Let the market decide if it is better, rather than forcing us.

• • This is true. However, every now and then someone tries to work out what this mystical packedstring library is and tries to use it (old invalid deps, etc.).

• The package has been stable for ~10 years -- why change a stable API? It is already "perfect"

• • As mentioned above: many people do not think that the current API is perfect.

• The new package really isn't the same package in any sense.

• • Sure it is: we might be changing the API, but it's the same basic concepts, etc. See current status here

• Rewrites by new teams damage the brand of famous packages (e.g. parsec 3)

• No additional breakages are introduced.

• • Not sure what your point is here.

• If you weren't maintainer of 'fgl' this rewrite wouldn't even be possible to call 'fgl' -- there's a conflict of interest.

• • Of course not, but I volunteered to become the maintainer of fgl precisely to modernise the interface (which as far as I know is why Martin Erwig gave fgl up for adoption: he didn't have time to make changes that people were asking him for).

• Maintaining Haskell98 compatability. Keep it simple. (See regex-posix's mistakes here)

• • Not sure what you mean by this point; what are regix-posix's mistakes? Whilst in general I can see Haskell98 (or Haskell2010) compatability being a good thing to keep (in case someone uses another compiler, etc.) if there's a good argument to be made for why a certain extension would be useful then why shouldn't we use it? Whilst I mightn't have been working on a major Haskell library back then, it was pointed out to me a while back that you shouldn't constrain yourself by enforcing Haskell98 compatability for no reason.

• • Non-point: FGL is already incompatible with Haskell98 (MPTCs, etc.).

• Distros that support the Haskell Platform will have to keep an old version of fgl around for a long time anyway.

• • I don't intend to have the new fgl be actually used by people for a while yet anyway, as I intend to get the ecosystem built up around it (fgl-algorithms, etc.) first.

• • I think that keeping base-3 compatibility in xmonad just to ensure that people using the Long Term Release of Ubuntu has in a sense held it back, as it was more of a pain to transition to base-4 later on than it would have been to do it earlier (using extensible-exceptions if nothing else).

• The original author might not approve of the use of the name.

• • If this is true, then why did he publicly state in mailing lists that he wanted someone to take over?

• having tutorials not work for later revisions is more confusing than having various packages doing the same thing.

• • The current tutorials do not fully work with the current version anyway, and we will be writing tutorials (already had one offer to help out with this).

• separate names (both for the package name and module name-space) is that its easier to have both packages installed at the same time

• • A valid argument, especially when seeing the fall-out between mtl and transformers.

• • • However, that means we'd have to think of new module names as well as a new package name, and I can't think of anything better/more appropriate than "Data.Graph.Inductive".

Possible Compromises

• Until we're ready to release, either don't release fgl on Hackage or call it fgl-experimental or something.

• The name "Functional Graph Library" is rather vague anyway, whereas something like "inductive-graphs" makes more sense in terms of the actual data structures, etc. involved. As such we could give the new version of the library something like that if down the track we could officially deprecate the fgl library (like how packedstring has been deprecated).

• We could officially split up the fgl package namespace even further: rather than having fgl + fgl-algorithms, etc. we could have something like fgl-classes, fgl-algorithms, etc. As such the base name is kept whilst there is no ambiguity on which version is being used.