-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
Follow README style guide #1140
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Follow README style guide #1140
Conversation
contributing.md
Outdated
| - Each JavaScript feature lives in its own file under [`source/features`](https://github.com/sindresorhus/refined-github/tree/master/source/features) and it's loaded on condition in [`source/content.js`](https://github.com/sindresorhus/refined-github/blob/master/source/content.js) | ||
| - Some GitHub pages are loaded via AJAX/PJAX, so some features need to be in the special `ajaxedPagesHandler` function (see it as a custom "on DOM ready") | ||
| - See what a _feature_ [looks like](https://github.com/sindresorhus/refined-github/blob/master/source/features/add-time-machine-links-to-comments.js) and [how it's loaded](https://github.com/sindresorhus/refined-github/blob/d7768508c3919558daa6b2ccc5a15aa73d081551/source/content.js#L176) (in this case it uses `observeEl` to automatically be run when new comments are loaded via AJAX) | ||
| - If you're making changes to the README, try to match the style of the content that's already there and when in doubt, take a look at [our little style guide](https://github.com/sindresorhus/refined-github/issues/1139) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll add a dot at the end of the sentence after the link here and on all other list items which don't have it here. It's just better as these are real sentences. I know this is not entirely related, but since this is about fixing markdown style..
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
None of the above items are either, they'll have to be updated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The first two items in the list have full stops at the end.
readme.md
Outdated
| - [Makes it possible to automatically merge a PR after its build has passed](https://user-images.githubusercontent.com/1402241/35192861-3f4a1bf6-fecc-11e7-8b9f-35ee019c6cdf.gif) | ||
| - Allows you to toggle all [outdated PR comments](https://user-images.githubusercontent.com/25818354/33240033-3e271588-d2af-11e7-93af-13b6e325f65d.gif) or [PR/Commit files](https://user-images.githubusercontent.com/1402241/35192652-6f79dc42-fec9-11e7-89ad-2b4a9c5f4f52.gif) with <kbd>alt</kbd> <kbd>click</kbd> | ||
| - Copies canonical link to file when [the <kbd>y</kbd> hotkey](https://help.github.com/articles/getting-permanent-links-to-files/) is used | ||
| - Supports indenting with the tab key in textareas like the comment box (<kbd>shift</kbd> <kbd>tab</kbd> for original behavior) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The first "tab" word here should be tab.
|
This could probably be tackled in a separate PR, but I'd recommend imperative language for describing added features: "Copy canonical link to file" vs "Copies canonical link to file" across all features. This follows popular commit convention by Linus Torvalds. The reasoninng is that you instruct Git to apply that change if you pick this commit. In the same way, you instruct the extension if you have that feature. It's similar to changelog formats based on commit messages following that convention. I guess I'm probably used to that, but I still like the brevity and clarity of the imperative form. |
|
@hkdobrev sounds good. I'd add dropping lets you/allows. Examples: - Allows you to toggle all outdated PR comments or PR/Commit files with <kbd>alt</kbd> <kbd>click</kbd>
+ Toggle all outdated PR comments or PR/Commit files with <kbd>alt</kbd> <kbd>click</kbd>
- Makes it possible to automatically merge a PR after its build has passed
+ Automatically merge a PR after its build has passed (checkbox)
- Supports indenting with the tab key in textareas like the comment box (<kbd>shift</kbd> <kbd>tab</kbd> for original behavior)
+ Indent with the <kbd>tab</kbd> key in textareas like the comment box (<kbd>shift</kbd> <kbd>tab</kbd> for original behavior) |
|
@hkdobrev @bfred-it There's a difference between Refined GitHub doing something by default (decluttering the UI) and it allowing the user to do something (copying a link). Using the same style for both cases might make users think Refined GitHub does things by default that actually have to be explicitly triggered/enabled by them. |
|
For reference, that’s also how Apple talks about what their software lets you do:
|
…ined-github into obey-readme-style-guide
I like the style they use. Adopting it requires adding the features' uses to the current descriptions that just say what they do. Here are a few examples:
What do you think about rewording the features in this way? |
|
Love it! The third one is a bit awkward, maybe it could be made passive:
|
| <li>Select the file <code>refined-github/distribution/manifest.json</code> | ||
| <li>Open <code>about:debugging#addons</code>. | ||
| <li>Click on the <strong>Load Temporary Add-on</strong> button. | ||
| <li>Select the file <code>refined-github/distribution/manifest.json</code>. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These should end with ; except the last one, which ends with .
3b56d99 to
b3947ec
Compare
|
Random ping: @shroudedcode resolve this before we have any merge conflicts later! |
889af37 to
b6d29ab
Compare
|
@ramlmn I'll fix the merge conflict on the weekend. I'm doing an internship this week and can barely focus on doing any kind of open source work in the evening. Also, please stop pinging people about their pull requests unless the pull request is really old and they have been active within the last few days (a sign that they might have actually forgotten about it). It comes off rude and often they have reasons for "abandoning" them for a while. |
237b9e6 to
b6d29ab
Compare
package.json
Outdated
| }, | ||
| "ignoreFiles": [ | ||
| "**/*.md" | ||
| ] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This doesn't seem to change the linter's output
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't know why but without this option the VS Code stylelint extension displays all sorts of errors in the readme.md file as if it was a stylesheet.
readme.md
Outdated
| <tr> | ||
| <th width="50%"> | ||
| Linkifies issue/PR references in code, comments and titles | ||
| Click on references to issues and pull requests |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe "Clickable references"
readme.md
Outdated
| - [Adds scoped search on each users profile page](https://user-images.githubusercontent.com/1402241/35185441-24ad4b1e-fe37-11e7-9e1b-0dc09fc1ada2.png) | ||
| - Toggle all [outdated PR comments](https://user-images.githubusercontent.com/25818354/33240033-3e271588-d2af-11e7-93af-13b6e325f65d.gif) or [PR/commit files](https://user-images.githubusercontent.com/1402241/35192652-6f79dc42-fec9-11e7-89ad-2b4a9c5f4f52.gif) with <kbd>alt</kbd> <kbd>click</kbd>. | ||
| - Copy the canonical link of a file with [the <kbd>y</kbd> hotkey](https://help.github.com/articles/getting-permanent-links-to-files/). | ||
| - Indent text with <kbd>tab</kbd> in textareas like the comment box (<kbd>shift</kbd> <kbd>tab</kbd> for original behavior). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe textareas or just "comment fields" (I don't know of any other textareas on this site)
readme.md
Outdated
| - Copy the canonical link of a file with [the <kbd>y</kbd> hotkey](https://help.github.com/articles/getting-permanent-links-to-files/). | ||
| - Indent text with <kbd>tab</kbd> in textareas like the comment box (<kbd>shift</kbd> <kbd>tab</kbd> for original behavior). | ||
| - [Use the pull request title as the commit title when merging with `Squash and merge`](https://github.com/sindresorhus/refined-github/issues/276). | ||
| - [Directly view linked gists inside comments without visiting the link.](https://user-images.githubusercontent.com/6978877/33911900-c62ee968-df8b-11e7-8685-506ffafc60b4.PNG) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think "embed" is clear enough to developers
readme.md
Outdated
| - Indent text with <kbd>tab</kbd> in textareas like the comment box (<kbd>shift</kbd> <kbd>tab</kbd> for original behavior). | ||
| - [Use the pull request title as the commit title when merging with `Squash and merge`](https://github.com/sindresorhus/refined-github/issues/276). | ||
| - [Directly view linked gists inside comments without visiting the link.](https://user-images.githubusercontent.com/6978877/33911900-c62ee968-df8b-11e7-8685-506ffafc60b4.PNG) | ||
| - [Search a user's content using the user-scoped search on their profile page.](https://user-images.githubusercontent.com/1402241/35185441-24ad4b1e-fe37-11e7-9e1b-0dc09fc1ada2.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe
Searches on user profiles are limited to the user.
readme.md
Outdated
| - [Copy a file's path using the `Copy path` button.](https://cloud.githubusercontent.com/assets/4201088/26023064/18c9c77c-37d2-11e7-8926-b0a05a2706ae.png) | ||
| - [Quickly access a commit's patch and diff using links.](https://cloud.githubusercontent.com/assets/737065/13605562/22faa79e-e516-11e5-80db-2da6aa7965ac.png) | ||
| - [View a repository at the time of a comment.](https://user-images.githubusercontent.com/1402241/32310022-7fef6174-bf5d-11e7-960f-5041a8f073ac.png) | ||
| - [Quickly access a user's public gists from their profile.](https://user-images.githubusercontent.com/11544418/34268306-1c974fd2-e678-11e7-9e82-861dfe7add22.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No "Quickly"
Also maybe just "Visit"
readme.md
Outdated
| - [Quickly access a commit's patch and diff using links.](https://cloud.githubusercontent.com/assets/737065/13605562/22faa79e-e516-11e5-80db-2da6aa7965ac.png) | ||
| - [View a repository at the time of a comment.](https://user-images.githubusercontent.com/1402241/32310022-7fef6174-bf5d-11e7-960f-5041a8f073ac.png) | ||
| - [Quickly access a user's public gists from their profile.](https://user-images.githubusercontent.com/11544418/34268306-1c974fd2-e678-11e7-9e82-861dfe7add22.png) | ||
| - [Jump to the bottom of a discussion page using the `Jump to bottom` link.](https://user-images.githubusercontent.com/4331946/34298950-93876584-e720-11e7-898a-96f85e31aefe.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Jump to the bottom of a discussion page with a click
readme.md
Outdated
| - [View a repository at the time of a comment.](https://user-images.githubusercontent.com/1402241/32310022-7fef6174-bf5d-11e7-960f-5041a8f073ac.png) | ||
| - [Quickly access a user's public gists from their profile.](https://user-images.githubusercontent.com/11544418/34268306-1c974fd2-e678-11e7-9e82-861dfe7add22.png) | ||
| - [Jump to the bottom of a discussion page using the `Jump to bottom` link.](https://user-images.githubusercontent.com/4331946/34298950-93876584-e720-11e7-898a-96f85e31aefe.png) | ||
| - [Quickly access `Your repositories` from the profile dropdown.](https://user-images.githubusercontent.com/4201088/34920280-479e2454-f996-11e7-8e24-ad69793b9d9b.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Quickly
readme.md
Outdated
| - [Quickly access a user's public gists from their profile.](https://user-images.githubusercontent.com/11544418/34268306-1c974fd2-e678-11e7-9e82-861dfe7add22.png) | ||
| - [Jump to the bottom of a discussion page using the `Jump to bottom` link.](https://user-images.githubusercontent.com/4331946/34298950-93876584-e720-11e7-898a-96f85e31aefe.png) | ||
| - [Quickly access `Your repositories` from the profile dropdown.](https://user-images.githubusercontent.com/4201088/34920280-479e2454-f996-11e7-8e24-ad69793b9d9b.png) | ||
| - [Download entire folders from repositories using the `Download folder` button.](https://user-images.githubusercontent.com/1402241/35044451-fd3e2326-fbc2-11e7-82e1-61ec7bee612b.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's add:
(it uses download-directory.github.io)
readme.md
Outdated
| - [Quickly access `Your repositories` from the profile dropdown.](https://user-images.githubusercontent.com/4201088/34920280-479e2454-f996-11e7-8e24-ad69793b9d9b.png) | ||
| - [Download entire folders from repositories using the `Download folder` button.](https://user-images.githubusercontent.com/1402241/35044451-fd3e2326-fbc2-11e7-82e1-61ec7bee612b.png) | ||
| - [Collapse or expand a repository's files using the :arrow_down_small: button.](https://user-images.githubusercontent.com/1402241/35480123-68b9af1a-043a-11e8-8934-3ead3cff8328.gif) | ||
| - [Quickly navigate to a repository's default branch or latest version tag using links.](https://user-images.githubusercontent.com/1402241/36961980-389bd2b0-2080-11e8-8bff-bb8af52e7128.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Quickly visit a repository's default branch and latest version tag
readme.md
Outdated
| - [Quickly see which comment a permalink links to.](https://user-images.githubusercontent.com/1402241/37349492-226bd37a-2709-11e8-8087-d9686b330240.png) | ||
| - [Inactive deployments in PR timelines are hidden.](https://github.com/sindresorhus/refined-github/issues/1144) | ||
|
|
||
| And [many](source/content.css) [more...](source/content.js) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And [many more…](source/content.css)content.js no longer contains any features
|
Sorry! Lots of notes. I should have just made the changes where I was sure |
Regarding the things I haven't changed yet:I'm trying to use the same style for all features: A sentence starting with an imaginary Refined GitHub allows you to … Having features that use a different style in between the others looks weird and is harder to read. I agree that some of the features still sound kind of awkward. If you have any suggestions on how to improve them while adhering to the style, let me know. |
1fb2c57 to
1baf430
Compare
|
I don’t think we can stick to just that. It’s preferrable to keep sentences short and readable instead, given that there’s a lot of them.
Is preferrable to
|
|
I've changed some of the features to sound less awkward and made sure that within a section they all use the same style. While for most features the "Apple style" works best (in my opinion), using the style for Declutter and UI improvements sounds awkward. That's why I've reworded them to use a different style. I still can't get myself to use multiple different styles within a section. It just looks so wrong. |
readme.md
Outdated
| - Indent text with <kbd>tab</kbd> inside comment fields (<kbd>shift</kbd> <kbd>tab</kbd> for original behavior). | ||
| - [Use the pull request title as the commit title when merging with `Squash and merge`](https://github.com/sindresorhus/refined-github/issues/276). | ||
| - [Directly view linked gists inside comments.](https://user-images.githubusercontent.com/6978877/33911900-c62ee968-df8b-11e7-8685-506ffafc60b4.PNG) | ||
| - [Directly view linked gists inside comments.](https://user-images.githubusercontent.com/6978877/33911900-c62ee968-df8b-11e7-8685-506ffafc60b4.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This new URL doesn't work. If you want to change case you'll have to re-upload it
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Woah, that's weird. Did GitHub generate .PNG URLs in the past?
I'll just remove the commit. Done.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, GitHub just preserves the extension as-is, so if you upload FILE.PNG you'll get 2cb44.PNG
e89fe2c to
6afcd0c
Compare
|
Alright let's merge this soon, at least partially, @shroudedcode doesn't have to deal with insane merge conflicts. Further changes can be suggested later. I'm going through it and making small changes |
hkdobrev
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👏
|
@shroudedcode thanks for this PR! I just had to make many of them passive because this was just too awkward:
and can just be:
Apple-like copy works when you can take an action, but not when things are. "Quickly see this and that" everywhere is just extra copy. |
Obeys the style guide proposed in #1139.
Closes #1139