Re: Typo in "27.2.8. Synchronous Replication"

On Tue, Jan 18, 2022 at 4:01 PM Eric Mutta <eric(dot)mutta(at)gmail(dot)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.