Re: Typo in "27.2.8. Synchronous Replication"

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.