Typo in "27.2.8. Synchronous Replication"

On Mon, Dec 27, 2021 at 12:07 AM PG Doc comments form
<noreply@postgresql.org> wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/14/warm-standby.html
Description:

The following sentence:

The minimum wait time is the round-trip time **between primary to

standby.**

Should either end with "...between primary AND standby" or end with "...FROM
primary to standby".

That's indeed correct. Fix pushed. I went with "primary and standby"
because that's the terminology used elsewhere in the same file.

--
Magnus Hagander
Me: https://www.hagander.net/
Work: https://www.redpill-linpro.com/

Hi Magnus, happy new year! Thanks for pushing the fix.

Coming from an SQL Server background where the docs are hosted on GitHub
and minor changes like this can be made by simply submitting a pull
request, I am wondering is there anything similar for the Postgres docs?

Going through a mailing list just to fix a typo feels like a lot of
overhead!

On Sun, Jan 2, 2022, 19:08 Magnus Hagander <magnus@hagander.net> wrote:

On Mon, Jan 3, 2022 at 03:40:40PM +0300, Eric Mutta wrote:

Hi Magnus, happy new year! Thanks for pushing the fix.

Coming from an SQL Server background where the docs are hosted on GitHub and
minor changes like this can be made by simply submitting a pull request, I am
wondering is there anything similar for the Postgres docs?

Going through a mailing list just to fix a typo feels like a lot of overhead!

No, sorry, there is not an easier way.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

If only the physical world exists, free will is an illusion.

On Mon, Jan 3, 2022 at 1:40 PM Eric Mutta <eric.mutta@gmail.com> wrote:

Hi Magnus, happy new year! Thanks for pushing the fix.

Coming from an SQL Server background where the docs are hosted on GitHub and minor changes like this can be made by simply submitting a pull request, I am wondering is there anything similar for the Postgres docs?

Going through a mailing list just to fix a typo feels like a lot of overhead!

Hi!

Personally, I would find sending an email to a mailing list or like
you did, filling out the form on the website, would be *less* overhead
than having to do a Pull Request (which would include checkout,
verifying builds etc, no?).

Can you enlighten me on exactly which part of the flow of that you
think would make it easier? Perhaps it's something we can adopt
something out of to make it easier for us as well. But I wonder if it
more has to do with the structure of the docs than the actual tool?
(That is, the error is on warm-standby.html, but the source is
actually in a file called high-availability.sgml)

//Magnus

Hi Magnus,

You are correct that doing a Pull Request would involve more overhead in
terms of checking out code, doing builds, etc, however GitHub automates
much of that and it all runs in the cloud so you can do it in a browser on
your phone while on the train if you wanted to. It literally takes a few
clicks from start to finish. Here's the flow from a real example:

1. There was a typo in the "Restore and Recovery Overview (SQL Server)"
docs here
https://docs.microsoft.com/en-us/sql/relational-databases/backup-restore/restore-and-recovery-overview-sql-server?view=sql-server-ver15

2. I noticed the typo and on the top right of the page there's an "edit"
link. Click that and it takes you to GitHub where the Markdown text is.
GitHub automatically creates a fork of the repo for me and opens an editor
where I can edit the Markdown, get a diff so I can review the changes, then
commit with a message.

3. After committing, GitHub shows a "Create Pull Request" button. Click
that and it automatically copies the commit message, opens an editor that
allows me to edit further if needed. For simple typos you usually just
submit the PR, which I did here
https://github.com/MicrosoftDocs/sql-docs/pull/6840

4. When a PR is submitted, one or more actions run automatically to check
for merge conflicts, to run any build steps, tests, etc. Note: up to this
point, nobody on the docs team has been involved: it's just me and the
automated processes on GitHub.

5. If the automated actions complete successfully THEN the responsible
person is notified. They can review the PR and merge it with one click.
GitHub also makes it super simple to discuss the edits, make further
commits, etc if the PR has issues. A complete history is made visible right
there in the browser.

The SQL Server Docs Team also has an automated process to push changes to
the live site, usually in a matter of hours and the really nice touch is
that once the changes are live, the committer is credited on the live site
with their GitHub avatar and name (e.g. for that fix, you can see mine
here:
https://docs.microsoft.com/en-us/sql/relational-databases/backup-restore/restore-and-recovery-overview-sql-server?view=sql-server-ver15
- it's the third avatar from the left with name ericmutta).

Postgres existed long before GitHub and long before the CI/CD development
flow (which GitHub makes really easy) became mainstream, so it may take
some time and effort to adopt it. I do think the time will be well spent
because it will allow the already great Postgres docs to get even better
and do so FASTER (note that you pushed the fix on 27/Dec last year but over
three weeks later, the live site here
https://www.postgresql.org/docs/14/warm-standby.html still doesn't reflect
the fix).

Hopefully that provides food for thought, and I will be happy to
contribute/help further in any way I can.

Many thanks,
Eric.

On Sun, Jan 16, 2022 at 8:31 PM Magnus Hagander <magnus@hagander.net> wrote:

On Tue, Jan 18, 2022 at 4:01 PM Eric Mutta <eric.mutta@gmail.com> wrote:

2. I noticed the typo and on the top right of the page there's an "edit"
link. Click that and it takes you to GitHub where the Markdown text is.

I suspect a large part of your expectation is based upon this and that
GitHub can display processed markdown natively. That is a huge difference
between the experience you describe here and our SGML-based documentation.

4. When a PR is submitted, one or more actions run automatically to check
for merge conflicts, to run any build steps, tests, etc. Note: up to this
point, nobody on the docs team has been involved: it's just me and the
automated processes on GitHub.

Honestly, if this part works well (and even the immediate single-page
editing), a functioning demonstration on a fork of our repo on GitHub would
go a long way. Even if that fork is only used to get to the point of
producing a pull request which the coder can then copy and paste into an
email message to -hackers to be formally applied to the codebase,
back-patched if necessary (we don't make authors worry about back-patching).

5. If the automated actions complete successfully THEN the responsible

person is notified. They can review the PR and merge it with one click.
GitHub also makes it super simple to discuss the edits, make further
commits, etc if the PR has issues. A complete history is made visible right
there in the browser.

Having both the PR and the mailing list be places where code reviews might
happen would be a concern - but the author can deal with that.

Postgres existed long before GitHub and long before the CI/CD development
flow (which GitHub makes really easy) became mainstream, so it may take
some time and effort to adopt it.

The desire to avoid entanglements on third-party services is a point made
by comitters that is impossible to avoid if leveraging GitHub. And the
barriers are much higher if we host our own (e.g., GitLab). But again,
people who only know how to compile PostgreSQL (a low bar to meet) and are
familiar with this ecosystem (a prerequisite if going down this path) can
experiment and proof-of-concept.

FYI, there is some current work being done to use Meson in the build
process (I haven't kept up with the details).

(note that you pushed the fix on 27/Dec last year but over three weeks
later, the live site here
https://www.postgresql.org/docs/14/warm-standby.html still doesn't
reflect the fix).

The docs and the source code are maintained in the same manner. Once
release 12.10 is published the v12 website and the source code will update
to that latest version. That is arguably a policy decision that any new
tooling would continue to adhere to. You can check that the current HEAD
has the patch because we do publish a development branch for that.

In short, the committers tend to get trivial fixes to the docs applied
without any difficulty or delay, even when presented with just a url link
and some suggestion text. The sgml overhead on those is minimal. While I
appreciate we could be even more cool if we used a more modern set of
features, the effort it would take to do so doesn't seem to match the
benefit we would get. Our documentation is, on the whole, a strength.

David J.

While I appreciate we could be even more cool if we used a more modern

set of features, the effort it would take to do so doesn't seem to match
the benefit we would get. Our documentation is, on the whole, a strength.

Many thanks David, for the clarification on how the documentation release
process works. I definitely agree that the Postgres docs are one of its
greatest strength (every time I found myself saying "wow, Postgres is
amazing!" it was when I was reading the docs, long before I even opened
psql). Thanks to all of you who devote your time and energy to the docs -
they really make a difference to those of us coming from other (commerical)
databases!

On Wed, Jan 19, 2022, 02:28 David G. Johnston <david.g.johnston@gmail.com>
wrote: