Re: proposal: psql –help reflecting service or URI usage

> On Mar 8, 2021, at 8:40 AM, Paul Förster <paul(dot)foerster(at)gmail(dot)com> wrote:
>
> Hi Mark,
>
>> On 08. Mar, 2021, at 16:39, Mark Dilger <mark(dot)dilger(at)enterprisedb(dot)com> wrote:
>>
>> Fortunately, the man pages and html docs are generated from the same sources. Those sources are written in sgml, and the tools to build the docs must be installed. From the top directory, execute `make docs` and if it complains about missing tools you will need to install them. (The build target is 'docs', but the directory containing the docs is named 'doc'.)
>
> so the help files I'd change would be doc/src/sgml/ref/psql-ref.sgml, doc/src/sgml/ref/pg_isready.sgml, etc.?

Yes

>> Oh, I'm quite sorry to hear that. The process of getting a patch accepted, especially the first time you submit one, can be discouraging. But the community greatly benefits from new contributors joining the effort, so I'd much rather you not withdraw the idea.
>
> I'd like to, and also I'd like to do all the bin/* tools (including wrapping the long line in pg_isready ;-)), as you suggested, but I don't know the process. In my first admittedly naive attempt, I just downloaded the source from https://www.postgresql.org/ftp/source/v13.2, unpacked it and made my changes there. Then I did a diff to the original and posted it here. I don't even know if this is the correct workflow. I saw gitgub being mentioned a couple of times but I don't have an account, nor do I even know how it works.
>
> I was pretty surprised to see the lines in PWN:
>
> "Paul Förster sent in a patch to mention database URIs in psql's --help output."
> "Paul Förster sent in another revision of a patch to mention URIs and services in psql --help's output."
>
> Is there a FAQ somewhere that describes how properly create patches, submit them and possibly get them released? Something like a step-by-step?
>
> Is github a must-have here?

No, github is not a must-have. I don't use a github account for my submissions. The project uses git for source code control, but that's not the same thing as requiring "github". The project switched from cvs to git a few years back.

If you can install git, using rpm or yum or whatever, then from the command line you can use

git clone https://git.postgresql.org/git/postgresql.git

and it will create a working directory for you. You can make modifications and commit them. When you are finished, you can run

git format-patch -v 1 master

and it will create a patch set containing all your changes relative to the public sources you cloned, and the patch will include your commit messages, which helps reviewers not only know what you changed, but why you made the changes, in your own words.

See https://wiki.postgresql.org/wiki/Development_information

>> If you need help with certain portions of the submission, such as editing the docs, I can help with that.
>
> as you see above, I'm curious to learn, though doing it to all the tools will take some time for me.
>
> Sorry, I'm a noob, not so much to C, but to the workflows here. Hence my questions may seem a little obvious to all the pros.

That's not a problem. If this gets too verbose for the list, we can take this off-list and I can still walk you through it.

—
Mark Dilger
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company