fix: typos and grammar #190
Conversation
via grammarly
There was a problem hiding this comment.
These are really excellent changes, thanks @jonas-jonas! This is a good reminder for me to add the grammarly plugin back to VSCode. A few minor nitpicks about details below, then this is ready to 🚀.
templates/repository/common/.github/ISSUE_TEMPLATE/DESIGN-DOC.yml
Outdated
Show resolved
Hide resolved
| - [Contribute to Ory $PROJECT](#contribute-to-ory-project) | ||
| - [Introduction](#introduction) | ||
| - [FAQ](#faq) | ||
| - [How can I contribute?](#how-can-i-contribute) | ||
| - [Communication](#communication) | ||
| - [Contribute examples](#contribute-examples) | ||
| - [Contribute code](#contribute-code) | ||
| - [Contribute documentation](#contribute-documentation) | ||
| - [Disclosing vulnerabilities](#disclosing-vulnerabilities) | ||
| - [Code style](#code-style) | ||
| - [Working with forks](#working-with-forks) | ||
| - [Conduct](#conduct) |
There was a problem hiding this comment.
This shouldn't get updated in a pull request that just fixes typos. Can you please revert this part?
There was a problem hiding this comment.
Not sure how that happens, but I think it's prettier in VSCode?
It automatically does this when I save the file... So this might be correct, actually? Do you know where this is coming from?
Co-authored-by: Kevin Goslar <[email protected]>
Co-authored-by: Kevin Goslar <[email protected]>
| - [Contribute to Ory $PROJECT](#contribute-to-ory-project) | ||
| - [Introduction](#introduction) | ||
| - [FAQ](#faq) | ||
| - [How can I contribute?](#how-can-i-contribute) | ||
| - [Communication](#communication) | ||
| - [Contribute examples](#contribute-examples) | ||
| - [Contribute code](#contribute-code) | ||
| - [Contribute documentation](#contribute-documentation) | ||
| - [Disclosing vulnerabilities](#disclosing-vulnerabilities) | ||
| - [Code style](#code-style) | ||
| - [Working with forks](#working-with-forks) | ||
| - [Conduct](#conduct) |
There was a problem hiding this comment.
This is still here. Please save the file without running Prettier by pressing ctrl-alt-s (on Linux or Windows). Not sure what the hotkey on macOS is.
Alternatively, you can stage (select to be committed) only certain parts of a document:
- on the CLI: run
git commit -p, then enteryif you want to commit the current part ornif you don't want to commit it - in VSCode: enter "Source Control" view, double-click to see the diff of your changes, highlight the changes to commit, right-click, and select "stage selected ranges". Git commits only the changes that are "staged". You can also un-stage changes by selecting and right-clicking them.
If it's easier, you can also revert only parts of a document (those which you don't want to commit). In the diff view, highlight the part to be reverted, right clicking, and choosing "revert selected ranges".
There was a problem hiding this comment.
My point was, that we should check why prettier is doing this.
Because the next time we (or anyone else) touches this file, they will run into the same issue. Currently, it doesn't seem possible with doctoc (see thlorenz/doctoc#213) to ignore headings though, so I don't think there is another way of solving this for now.
Done. PTAL.
There was a problem hiding this comment.
I don't think Prettier is doing this since Prettier never changes content like this (it only formats it) and TOC are not even an official part of the Markdown spec. This is done by a much more invasive tool. I suspect a VSCode plugin like https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one here. That's at least the culprit in my setup. Super useful plugin btw.
There was a problem hiding this comment.
Ohh, right! That's true. I have it installed too...
Well, then we could add <!-- omit in toc --> (see [1] from their README) to the end of the heading # Contribute to Ory $PROJECT. I am not sure if that'll break anything, though. I tested it and at least it doesn't generate the heading into the TOC anymore. WDYT?
1:
There was a problem hiding this comment.
Sounds promising. Since that's a separate issue and this branch is shipped already, do you want to give it a try in a separate feature branch?
Is this stuck or something? |
Yes, I believe so. Let's wait for @kevgo to approve. |
There was a problem hiding this comment.
This PR is a big step up for the developer experience. Such details shape the perception of how mature (and thereby trustworthy) our org and its processes are.
It keeps amazing me how many issues good automation finds even in very carefully human-written and human-reviewed content like the Markdown in this PR. Vincent and I have reviewed and improved on it so many times and still. The exact same thing applies to human-written source code. Modern test tools still find bugs even in decades-old Unix tools that are heavily battle tested and had thousands of eyeballs on them. To me this says something about how complementary the strengths and weaknesses of humans (creative/friendly/empathic but slow/sloppy/unreliable) vs machines (fast/exact/logical but unoriginal/uncreative).
Let's keep this high level of excellence by using all available tools (free and the best ones money can buy) like syntax and grammar checkers, readability checkers, linters, type checkers, test programs, etc.
via grammarly (https://marketplace.visualstudio.com/items?itemName=znck.grammarly)