doc: make pull-request guide default branch agnostic #41299
Conversation
|
Review requested:
|
| $ cd node | ||
| $ git remote add upstream https://github.com/nodejs/node.git | ||
| $ git fetch upstream | ||
| ```sh |
There was a problem hiding this comment.
Non-blocking but this change results in wonky highlighting that makes no sense to me.
This is because sh makes it think it's syntax-highlighting a bash script rather than rendering shell CLI stuff. I think txt is better.
There was a problem hiding this comment.
I think text make no sense semantically speaking. I don't feel strongly about syntax highlighting though, maybe we should disable syntax highlighting for (ba)sh altogether? From a quick glance it looks like it's never useful (and sometimes it even adds confusion as this one). If that sounds good to you, I can open a PR doing that.
There was a problem hiding this comment.
If that sounds good to you, I can open a PR doing that.
Is it possible to do that? This is a document that gets displayed in the GitHub interface, not on our web pages.
There was a problem hiding this comment.
Ah no, we don't have control over this indeed, I thought you meant the HTML version of the docs
There was a problem hiding this comment.
A valid flag in Linguist (which is what the GitHub interface uses) is fundamental. It's an alias for text but maybe it is more semantically tolerable?
Another possibility is to adjust our rules to omit use of a flag when it makes sense.
And one more possibility would be to not use code blocks for this sort of thing. Like, in HTML, these kind of code blocks might be a <code> elements but maybe these kind of "here's a list of commands to run" should really be <pre> elements or something else?
There was a problem hiding this comment.
And of course the two status quo options:
- Don't worry about the wonky highlighting.
- Use
textand either convince ourselves that it makes sense semantically or don't worry that maybe it doesn't.
There was a problem hiding this comment.
If I had unlimited time and motivation, I would track down which library GitHub is using for syntax highlighting and beg them to get rid of this keyword highlighting which is more confusing than helping. But since I don’t: I think, like the bash vs sh discussion we had, since the semantic is not really a user facing feature, it should not matter and we should use whatever works with the current config (so text). I would still be very interested to know if the semantic part resonates with others, in particular Id be interested to know if that makes any difference to folks using a screen reader to collaborate.
There was a problem hiding this comment.
If I had unlimited time and motivation, I would track down which library GitHub is using for syntax highlighting and beg them to get rid of this keyword highlighting which is more confusing than helping.
GitHub uses https://github.com/github/linguist.
Valid flags are definied in https://github.com/github/linguist/blob/master/lib/linguist/languages.yml.
They say they use Linguist for detection but it's not clear to me that it's used for actual highlighting.
I would still be very interested to know if the semantic part resonates with others, in particular Id be interested to know if that makes any difference to folks using a screen reader to collaborate.
Since screen readers use the HTML output in the GitHub interface, and the language flags end up as CSS, class attributes, and things like that, I doubt they play a semantic role for many from an a11y perspective. (But the weird highlighting might.) The exception would be someone reading raw markdown (whether with assistive technology or not).
Co-authored-by: Rich Trott <rtrott@gmail.com>
aduh95
added
author ready
|
Landed in c5ac0c6 |
Refs: nodejs#33864 PR-URL: nodejs#41299 Reviewed-By: Rich Trott <rtrott@gmail.com>
Refs: #33864