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.