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).
GRANT reference doc page
I’ll take the example of a simple patch : in the
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
The other option is to already know the source. The SQL reference pages are
ref directory. My page is called
sql-grant.html meaning, I’m
Changing the file
I decided to do something simple, so I just added
materialized views to the
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.
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 firstname.lastname@example.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.