News

Welcome to End Point’s blog

Ongoing observations by End Point people

Postgres searchable release notes - one page with all versions

The inability to easily search the Postgres release notes has been a long-standing annoyance of mine, and a recent thread on the pgsql-general mailing list showed that others share the same frustration. One common example when a new client comes to End Point with a mysterious Postgres problem. Since it is rare that a client is running the latest Postgres revision (sad but true), the first order of business is to walk through all the revisions to see if a simple Postgres update will cure the problem. Currently, the release notes are arranged on the postgresql.org web site as a series of individual HTML pages, one per version. Reading through them can be very painful - especially if you are trying to search for a specific item. I whipped up a Perl script to gather all of the information, reformat it, clean it up, and summarize everything on one giant HTML page. This is the result: https://bucardo.org/postgres_all_versions.html

Please feel free to use this page however you like. It will be updated as new versions are released. You may notice there are some differences from the original separate pages:

  • All 270 versions are now on a single page. Create a local greppable version with:
    links -dump https://bucardo.org/postgres_all_versions.html > postgres_all_versions.txt
  • All version numbers are written clearly. The confusing "E.x.y" notation was stripped out
  • A table of contents at the top allows for jumping to each version (which has the release date next to it).
  • Every bulleted feature has the version number written right before it, so you never have to scroll up or down to see what version you are currently reading.
  • If a feature was applied to more than one version, all the versions are listed (the current version always appears first).
  • All CVE references are hyperlinks now.
  • All "mailtos" were removed, and other minor cleanups.
  • Replaced single-word names with the full names (e.g. "Massimo Dal Zotto" instead of "Massimo") (see below)

Here's a screenshot showing the bottom of the table of contents, and some of the items for Postgres 9.4:

The name replacements took the most time, as some required a good bit of detective work. Most were unambiguous: "Tom" became "Tom Lane", "Bruce" became "Bruce Momjian", and so on. For the final document, 3781 name replacements were performed! Some of the trickier ones were "Greg" - both myself ("Greg Sabino Mullane") and "Greg Stark" had single-name entries. Similar problems popped up with "Ryan", and with "Peter" *not* being the familiar Peter Eisentraut (but Peter T. Mount) threw me off for a second. The only one I was never able to figure out was "Clark", who is attributed (via Bruce) with "Fix tutorial code" in version 6.5. Pointers or corrections welcome.

Hopefully this page will be of use to others. It's a very large page, but not remarkably wasteful of space, like many HTML pages these days. Perhaps some of the changes will make their way to the official docs over time.

16 comments:

Adrian Klaver said...

This is very nice and will definitely make my life easier. Is there a proposal out there to include this in the official documentation? If so I would gladly put my 2 cents in.

Joe said...

This lack of searchability within the official release notes appears to be another manifestation of the lack of a bug tracker ...

Bruce Momjian said...

Oh, you might want to add an HTML title to the web page so when people bookmark it, it has a meaningful title.

Greg Sabino Mullane said...

Bruce: done, thanks.

Greg Sabino Mullane said...

Adrian: no proposal yet, although I may work on a doc patch to correct the names. Any help is welcome.

Marko Tiikkaja said...

@Joe: That does not make any sense, and you know it.

Baron Schwartz said...

I have a different suggestion -- ask Swiftype to donate an account to the PostgreSQL community, and add that to the generated HTML for the documentation, release notes, etc. Their solution is really amazing and it's as easy as adding a small JS snippet to the HTML. (I am not associated with them in any way.)

PL said...

Look at "Building the documentation" section
http://www.postgresql.org/docs/9.4/interactive/docguide-build.html

You can build a single html file or pdf file for searching in the whole docs.

Even more, PDF version available here:
http://www.postgresql.org/docs/manuals/

Joe said...

@Marko: I'm not sure what am I supposed to know or why do you think it doesn't make sense. What I do know is that if there *was* a proper bug tracker, then you could search the bugs database and find when a bug was closed, etc. Maybe you can explain *why* it doesn't make sense.

Big 40wt Svetlyak said...

Guys, nice idea to collect all PostgreSQL's release notes in one place. But this file is static and should be updated manually, right?

I've added PostreSQL's release notes to AllMyChanges.com, and now you could subscribe and to be notified about all future updates:

http://allmychanges.com/p/soft/postgresql/

This service also shows all release notes on one page and moreover, it tracks them automatically.

I'm a developer of allmychanges, so feel free to send me any suggestions to sasha@allmychanges.com.

Big 40wt Svetlyak said...

By the way, thank you for the discussion. It gave me an amazing idea — to generate a Dash docset with all release notes you track at allmychanges.

Dash is an great offline viewer for OSX and iOS: http://kapeli.com/dash

Greg Sabino Mullane said...

Baron, it is unlikely the project will adopt any third-party commercial solutions, but do you have an open-source project already using it we can take a look at?

Unknown said...

Very nice indeed! I'm looking for information about the changes in the minor releases (e.g. 9.4.4-1 and 9.4.4-3) and could not find anything. Do you know where this is available?
Thanks

Greg Sabino Mullane said...

Unknown, the information for each revision (what you are calling a minor release perhaps?) is available. Just click on the version link at the top of the page. For example, here is 9.4.1: https://bucardo.org/postgres_all_versions.html#version_9.4.1. The version examples you gave (9.4.4-1 and 9.4.4-3) are not the ones used by Postgres itself.

vyegorov said...

@Greg, is it possible to create this as a sql dump to load data into the pre-defined tables?
It'll provide more querying possibilities.

Greg Sabino Mullane said...

vyegorov: I'm not honestly sure how useful that would be, as both DuckDuckGo and Google have already indexed the page, and they are better at searching than we ever will be. :) If you have a more specific use case, I'm happy to listen.