Thread: Typo in "27.2.8. Synchronous Replication"
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".
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, 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/
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 simplysubmitting 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 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
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:
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.