With each GHC release, create an upgrade guide for package maintainers

[sjakobi]

With each GHC release, hundreds of package maintainers have to figure out how to make their packages compile with the new GHC and silence all the warnings. A simple guide that documents the necessary changes would help reduce the maintenance cost spent on GHC upgrades.

Format

• I think a curated Markdown document in version control similar to Tekmo's "State of the Haskell ecosystem" could achieve a good balance of quality and being easy to contribute to. If that puts too much work on a single person or small group of people, a Wiki article might be better.

• The document should contain the error messages, that one is likely to encounter on the first run with the new GHC.

• The default recommendations should be for the case that the maintainer wants to keep compatibility with the previous GHC version, but alternative recommendations should also be included.

Possible extensions

• If desired or necessary, the format could be extended to give recommendations not only for the builtin packages (base, containers, mtl etc) but for any package that necessitates non-trivial code updates. Alternatively, upgrade instructions could potentially be included in changelogs.

• Ideally, upgrades to new GHC versions could be performed automatically by some sort of CLI tool. That may be quite difficult though…

[Gurkenglas]

If the automation's going to happen, it should probably be rolled out in the same format and release as this feature.

[hvr]

This sounds a lot like what I intended https://ghc.haskell.org/trac/ghc/wiki/Migration to be...

[sjakobi]

This sounds a lot like what I intended https://ghc.haskell.org/trac/ghc/wiki/Migration to be...

Oh, great, that's all I ever wanted! I simply hadn't found it when I googled for "ghc upgrade guide". Would you consider renaming that page to "Migration & Upgrade Guide" or getting the word "upgrade" on that page in a different way? Maybe there are other SEO options, but I know nothing about this.

[sjakobi]

@hvr: After reading this SEO guide, I think that the GHC wiki articles would be easier to find if they used the actual headlines in the title ("Why not Github" instead of "WhyNotGithub") and if they used the "description" meta tag. What's the proper place to discuss the Wiki setup?

[hvr]

@sjakobi for things that live in ghc.haskell.org/trac/ghc/ you can simply just use GHC Trac's ticket tracker in a self-referential way; there is a component "Trac & Git" for this purpose

[neongreen]

@sjakobi Apparently it's hard to do with Trac – see https://trac.edgewall.org/ticket/11163 and https://trac.edgewall.org/ticket/2717.

[sjakobi]

@sjakobi Apparently it's hard to do with Trac – see https://trac.edgewall.org/ticket/11163 and https://trac.edgewall.org/ticket/2717.

Thanks, that doesn't look to good. I think this severely limits the search ranking for wiki pages like the migration guide. Personally, I think that it is very important that the information in the Migration guide can be easily found through Google and other search engines.

@hvr: Would you consider moving the migration guide to another site, maybe a simple Github repo like https://github.com/Gabriel439/post-rfc/blob/master/sotu.md? I'd also propose renaming it to "GHC Upgrade Guide" – "upgrade" is IMO the more common term for a "migration" in this sense.

[gbaz]

Moving the guide to improve search ranking seems sort of overkill. Why not just suggest more places that can link to it to help with discoverability (and I guess also with pagerank)?

[sjakobi]

Moving the guide to improve search ranking seems sort of overkill. Why not just suggest more places that can link to it to help with discoverability (and I guess also with pagerank)?

I said I didn't know much about SEO! :) I'll try to come up with places that could link to the guide!