search

sorin-ionescu / prezto

The configuration framework for Zsh
MIT License
13.98k stars 4.49k forks source link

general: Reformat documentation with better formatting and wording #1914

Closed indrajitr closed 3 years ago

indrajitr commented 3 years ago

General purpose reformating and rewording in (a few places). This should also make markdown linting happier.

Prefer back-ticks wherever useful and use console for code blocks to be executed on terminal.

Also, update references links wherever possible (including update from 'http://' to 'https://').

jeffwidman commented 3 years ago

I think as a general rule it'd be better to wait a few days for another maintainer to review before merging, and then maybe nudge comment. I realize this is just formatting and slight rewording changes, but even so I've seen many such PR's over the years on various projects that ended up benefiting from code review. And given that it's formatting/docs, it's not like this has to be merged immediately. 😀

Additionally, beyond spotting typos etc, it also keeps the project's collaborative culture by giving the rest of us a chance to ask questions and learn so that in the future we better understand how to format stuff (perhaps you used a nifty markdown trick in here I don't know...).

Anyway, no need to revert or anything, but just in general can we aim for that unless it's a time-sensitive bugfix?

Lastly, thanks for the hard work here, I think the formatting looks a lot better in general. 👍

cc @belak

jeffwidman commented 3 years ago

Hah, just saw @belak 's comment on https://github.com/sorin-ionescu/prezto/pull/1915#issuecomment-832887368 about merging w/o waiting on doc changes.

I think in general, waiting at least 48 hours is probably okay... a minor typo fix makes sense, but something that touches > 1K LOC, even if it's only docs changes, well, I'd certainly feel a little better if there was a second set of eyes on it...

indrajitr commented 3 years ago

I think in general, waiting at least 48 hours is probably okay... a minor typo fix makes sense, but something that touches > 1K LOC, even if it's only docs changes, well, I'd certainly feel a little better if there was a second set of eyes on it...

Yep, agreed 💯 In general, at least having few more pairs of eyes (and at least one review approval) is always useful. That's what I usually follow (unless it is a trivial one, or has a bug). This one was sitting for a couple of days, and I didn't notice that you actually didn't approve this one when you approved the other ones en masse a few hours ago :)

jeffwidman commented 3 years ago

Hah, so you totally did wait 2 days! I missed that, I guess I'm just that far behind in my email. 😀