Patching Postgres' Documentation

Β· 679 words Β· 4 minute read

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 careful, 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 misread. 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 makefile 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 a 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 litle digest :

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

If you succeeded, you’ll find an HTML directory where you’ll find an 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 a 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 guideline 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 feedback 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 an 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.