Skip to content

Conversation

@niklashigi
Copy link
Contributor

Obeys the style guide proposed in #1139.

Closes #1139

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)
Copy link
Contributor

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..

Copy link
Member

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

Copy link
Contributor

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)
Copy link
Contributor

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.

@hkdobrev
Copy link
Contributor

hkdobrev commented Mar 6, 2018

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.

@fregante
Copy link
Member

fregante commented Mar 6, 2018

@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)

@niklashigi
Copy link
Contributor Author

@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.

@fregante
Copy link
Member

fregante commented Mar 7, 2018

For reference, that’s also how Apple talks about what their software lets you do:

Open a picture in a third‑party photo editing app like Photoshop or Pixelmator directly from Photos, and your edits will automatically be saved in your Photos library. You can also download third‑party project extensions from the Mac App Store that let you order framed prints, create web pages, and more, right from the Photos app.

Personalize your browsing experience in Safari by enabling settings for individual websites, like page zoom level, location services, notifications, and content blockers. So each website appears just how you like it.

Easily make sophisticated contrast and color adjustments to your photos with powerful tools like Curves for fine‑tuning contrast and Selective Color to make any color more saturated. And new, professionally inspired filters let you quickly give your pictures a distinctive look.

Instantly filter photo collections by your favorite criteria. A new selection counter keeps track of what you’ve selected, and lets you drag and drop collected images into an album or export them to the desktop. You can also rotate and favorite batches of images right from the toolbar.

@fregante fregante changed the title Obey README style guide Follow README style guide Mar 7, 2018
@niklashigi
Copy link
Contributor Author

niklashigi commented Mar 10, 2018

For reference, that’s also how Apple talks about what their software lets you do:

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?

@fregante
Copy link
Member

Love it! The third one is a bit awkward, maybe it could be made passive:

  • Destructive buttons are moved away from the primary button

@fregante fregante added the meta Related to Refined GitHub itself label Mar 11, 2018
<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>.
Copy link
Member

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 .

@ramlmn
Copy link

ramlmn commented Mar 22, 2018

Random ping: @shroudedcode resolve this before we have any merge conflicts later!

@niklashigi niklashigi force-pushed the obey-readme-style-guide branch from 889af37 to b6d29ab Compare March 22, 2018 21:56
@niklashigi
Copy link
Contributor Author

niklashigi commented Mar 22, 2018

@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.

@fregante fregante changed the title Follow README style guide WIP: Follow README style guide Mar 23, 2018
@niklashigi niklashigi force-pushed the obey-readme-style-guide branch from 237b9e6 to b6d29ab Compare March 24, 2018 12:30
@niklashigi
Copy link
Contributor Author

The pull request is by the way ready for review again. @bfred-it @hkdobrev

package.json Outdated
},
"ignoreFiles": [
"**/*.md"
]
Copy link
Member

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

Copy link
Contributor Author

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
Copy link
Member

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).
Copy link
Member

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)
Copy link
Member

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)
Copy link
Member

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)
Copy link
Member

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)
Copy link
Member

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)
Copy link
Member

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)
Copy link
Member

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)
Copy link
Member

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)
Copy link
Member

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

@fregante
Copy link
Member

Sorry! Lots of notes. I should have just made the changes where I was sure

@niklashigi
Copy link
Contributor Author

niklashigi commented Mar 25, 2018

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.

@niklashigi niklashigi force-pushed the obey-readme-style-guide branch from 1fb2c57 to 1baf430 Compare March 25, 2018 19:48
@fregante
Copy link
Member

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.

  • People have fled

Is preferrable to

  • The boats have allowed people to flee

@niklashigi
Copy link
Contributor Author

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)
Copy link
Member

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

Copy link
Contributor Author

@niklashigi niklashigi Mar 28, 2018

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.

Copy link
Member

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

@niklashigi niklashigi force-pushed the obey-readme-style-guide branch from e89fe2c to 6afcd0c Compare March 28, 2018 09:00
@fregante
Copy link
Member

fregante commented Mar 29, 2018

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

@fregante fregante self-assigned this Mar 29, 2018
Copy link
Contributor

@hkdobrev hkdobrev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👏

@fregante fregante merged commit 02a14cd into refined-github:master Mar 29, 2018
@fregante fregante changed the title WIP: Follow README style guide Follow README style guide Mar 29, 2018
@fregante
Copy link
Member

fregante commented Mar 29, 2018

@shroudedcode thanks for this PR!

I just had to make many of them passive because this was just too awkward:

Quickly determine what file you're looking at with the sticky file headers on pull requests.

and can just be:

File headers are always visible when scrolling.

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.

@niklashigi niklashigi deleted the obey-readme-style-guide branch March 29, 2018 12:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

meta Related to Refined GitHub itself

Development

Successfully merging this pull request may close these issues.

4 participants