Skip to content
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.

Sign up for GitHub

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

Jump to bottom

doc: avoid _may_ in collaborator guide #34749

Closed
wants to merge 0 commits into from
Closed

doc: avoid _may_ in collaborator guide #34749

wants to merge 0 commits into from

Conversation

Trott
Copy link
Member

@Trott Trott commented Aug 12, 2020

Many style guides (including Microsoft's) suggest avoiding may because
it can be unclear. Using can or might tends to increase clarity.

An example in this change:

They may not change to a Runtime Deprecation until the next major
release.

It's not clear if that means "They can not change until the next major
release" or "They might not change until the next major release but also
might change before then". Using can or might instead of may
clears up the ambiguity.

Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/c/can-may

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Aug 12, 2020
jasnell
jasnell approved these changes Aug 12, 2020
View reviewed changes
Copy link
Member

@jasnell jasnell left a comment

Choose a reason for hiding this comment

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

It's going to be very difficult to change this spec author's habits with regards to using "may" ......

@Trott
Copy link
Member Author

Trott commented Aug 12, 2020

Rebased to resolve conflicts and force-pushed.

@rickyes rickyes added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Aug 14, 2020
@Trott
Copy link
Member Author

Trott commented Aug 14, 2020

It's going to be very difficult to change this spec author's habits with regards to using "may" ......

I think you mean to say:

This spec author's habits may be very difficult to change.

@Trott
Copy link
Member Author

Trott commented Aug 14, 2020

Landed in 8640cd6

Trott added a commit that referenced this pull request Aug 14, 2020
@Trott
doc: avoid _may_ in collaborator guide
8640cd6 
Many style guides (including Microsoft's) suggest avoiding _may_ because
it can be unclear. Using _can_ or _might_ tends to increase clarity.

An example in this change:

> They may not change to a Runtime Deprecation until the next major
> release.

It's not clear if that means "They can not change until the next major
release" or "They might not change until the next major release but also
might change before then". Using _can_ or _might_ instead of _may_
clears up the ambiguity.

Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/c/can-may

PR-URL: #34749
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Shingo Inoue <leko.noor@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
@Trott Trott closed this Aug 14, 2020
@Trott Trott deleted the cg-may branch August 14, 2020 22:26
MylesBorins pushed a commit that referenced this pull request Aug 17, 2020
@Trott @MylesBorins
doc: avoid _may_ in collaborator guide
66fcd68 
Many style guides (including Microsoft's) suggest avoiding _may_ because
it can be unclear. Using _can_ or _might_ tends to increase clarity.

An example in this change:

> They may not change to a Runtime Deprecation until the next major
> release.

It's not clear if that means "They can not change until the next major
release" or "They might not change until the next major release but also
might change before then". Using _can_ or _might_ instead of _may_
clears up the ambiguity.

Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/c/can-may

PR-URL: #34749
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Shingo Inoue <leko.noor@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
@danielleadams danielleadams mentioned this pull request Aug 20, 2020
Merged
BethGriggs pushed a commit that referenced this pull request Aug 20, 2020
@Trott @BethGriggs
doc: avoid _may_ in collaborator guide
3925fd6 
Many style guides (including Microsoft's) suggest avoiding _may_ because
it can be unclear. Using _can_ or _might_ tends to increase clarity.

An example in this change:

> They may not change to a Runtime Deprecation until the next major
> release.

It's not clear if that means "They can not change until the next major
release" or "They might not change until the next major release but also
might change before then". Using _can_ or _might_ instead of _may_
clears up the ambiguity.

Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/c/can-may

PR-URL: #34749
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Shingo Inoue <leko.noor@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
addaleax pushed a commit that referenced this pull request Sep 22, 2020
@Trott @addaleax
doc: avoid _may_ in collaborator guide
6646dec 
Many style guides (including Microsoft's) suggest avoiding _may_ because
it can be unclear. Using _can_ or _might_ tends to increase clarity.

An example in this change:

> They may not change to a Runtime Deprecation until the next major
> release.

It's not clear if that means "They can not change until the next major
release" or "They might not change until the next major release but also
might change before then". Using _can_ or _might_ instead of _may_
clears up the ambiguity.

Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/c/can-may

PR-URL: #34749
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Shingo Inoue <leko.noor@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
addaleax pushed a commit that referenced this pull request Sep 22, 2020
@Trott @addaleax
doc: avoid _may_ in collaborator guide
09687b8 
Many style guides (including Microsoft's) suggest avoiding _may_ because
it can be unclear. Using _can_ or _might_ tends to increase clarity.

An example in this change:

> They may not change to a Runtime Deprecation until the next major
> release.

It's not clear if that means "They can not change until the next major
release" or "They might not change until the next major release but also
might change before then". Using _can_ or _might_ instead of _may_
clears up the ambiguity.

Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/c/can-may

PR-URL: #34749
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Shingo Inoue <leko.noor@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
@codebytere codebytere mentioned this pull request Sep 28, 2020
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jvmazagao jvmazagao jvmazagao approved these changes

@trivikr trivikr trivikr approved these changes

@lpinca lpinca lpinca approved these changes

@Leko Leko Leko approved these changes

@antsmartian antsmartian antsmartian approved these changes

@jasnell jasnell jasnell approved these changes

Assignees
No one assigned
Labels
author ready PRs that have at least one approval, no pending requests for changes, and a CI started. doc Issues and PRs related to the documentations.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
9 participants
@Trott @jasnell @antsmartian @Leko @lpinca @trivikr @jvmazagao @nodejs-github-bot @rickyes