Patching Postgres' Documentation

December 14, 2018
Hacking PostgreSQL Documentation

Creating a documentation patch is not easier than writing a code patch. I would say it can be harder than writing code. It’s just that difficulties don’t lie in the same place.

Writing code is technically hard and you can make things go very wrong if you’re not carefull, but writing poor docs is particularly bad for a project. You need to put yourself in the shoes of the reader to be sure your text can’t be missread. Sometimes you’ll find a word that’s neutral to you and with a negative connotation for others. That’s the way it is with humans and with trying to explain ideas with words.

I won’t explain here how to write good docs, because I simply don’t know… I’ll explain how to write a PostgreSQL documentation patch (the technical part).

Changing the GRANT reference doc page

I’ll take the example of a simple patch : in the GRANT reference page, the ALL TABLE clause is explained as

ALL TABLES also affects views and foreign tables, just like the specific-object GRANT command.

The question I was asked was : how about materialized views ?

It seemed pretty obvious to me that materialized views were included (but I tested it to be sure) but it wasn’t explicitly written. So I had to add it.

Identifying what file to change

The page documentation’s URL is https://www.postgresql.org/docs/current/sql-grant.html. First, I simply know that the file I’m looking for is in the doc/src/sgml directory. Because doc is the directory where we will find documentation, src is for “source” and in that src directory there’s nothing else than a makfile and the sgml directory.

Then, I have two options. The simplest (and the one that will always work) is to grep a phrase from the page you want to change.

 $ grep "also affects views and foreign tables" -r .
./html/sql-grant.html:   TABLES</code> also affects views and foreign tables,
just like the
./man7/GRANT.7:also affects views and foreign tables, just like the
specific\-object
./ref/grant.sgml:   TABLES</literal> also affects views and foreign tables, just
like the

The html and man7 directory are there simply because I already built the documentation on my laptop.

The file I’m looking for is doc/src/sgml/ref/grant.sgml.

The other option is to already know the source. The SQL reference pages are under the ref directory. My page is called sql-grant.html meaning, I’m looking for grant.sgml.

Changing the file

I decided to do something simple, so I just added materialized views to the phrase:

ALL TABLES also affects views, materialized views and foreign tables, just like the specific-object GRANT command.

I thought, maybe I could add partition table to that phrase. That’s a question I’ll ask Postgres hackers when I’ll post the patch.

Building documentation

You’ll find any information you need here.

Here is a litlle digest :

 ~/postgresql $ ./configure
 ~/postgresql $ cd doc/src/sgml/
 ~/postgresql/doc/src/sgml $ make STYLE=website html

If you suceeded, you’ll find a html directory where you’ll find a index.html file. Open it and navigate to the page you changed to be sure it’s well updated.

Creating the patch

The community has an history of patches with context. That means either you had to set up your git environment to provide git diff with context or you used the old trick of git diff | filterdiff --format=context.

Nowadays, it’s not mandatory anymore. So you can simply launch git diff and get the result in a text file. There is no guileline about how to name your patch. It just needs to be unique (and it’s better if it’s human readable).

git diff > ~/patch/sql-grant-documentation-adding-mat-views-to-all-tables_v1.patch

Submitting the patch

To submit a patch, simply send a mail to pgsql-hackers@postgresql.org. Then you may have a lot of feedbacks and it’s perfectly normal. People are always asking if a change is relevant or if that change can be made better.

For my first documentation patch, we had a 11 e-mails thread, even if my patch was a tiny minor change (just as that one). Don’t get upset about it, it’s the way we can make PostgreSQL better.

Don’t forget to register your patch to the next commitfest.

Can't connect to Postgres

March 30, 2020
Administration PostgreSQL Troubleshooting

Restoring Through timeline change

March 24, 2020
Installation PostgreSQL

What's wrong with Postgres?

March 22, 2020
Administration PostgreSQL Troubleshooting