Re: Typo in "27.2.8. Synchronous Replication"
| От | Eric Mutta |
|---|---|
| Тема | Re: Typo in "27.2.8. Synchronous Replication" |
| Дата | |
| Msg-id | CABb8_QZejYN0WPOQ=o3maacnpSRB-e-scS7L5-8Gk6eJtyBv-Q@mail.gmail.com обсуждение исходный текст |
| Ответ на | Re: Typo in "27.2.8. Synchronous Replication" (Magnus Hagander <magnus@hagander.net>) |
| Ответы |
Re: Typo in "27.2.8. Synchronous Replication"
("David G. Johnston" <david.g.johnston@gmail.com>)
|
| Список | pgsql-docs |
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
В списке pgsql-docs по дате отправления: