From e5ebb33ae94dcd4c50f0f686ee6e467f922ad95a Mon Sep 17 00:00:00 2001 From: Honza Javorek Date: Mon, 8 Sep 2025 11:59:07 +0200 Subject: [PATCH] feat: update Microsoft styles Extracted from https://github.com/apify/apify-docs/pull/1890/ --- .github/styles/Microsoft/Accessibility.yml | 11 +- .github/styles/Microsoft/Adverbs.yml | 4 +- .github/styles/Microsoft/ComplexWords.yml | 120 ------------------ .github/styles/Microsoft/Dashes.yml | 6 +- .github/styles/Microsoft/FirstPerson.yml | 4 +- .github/styles/Microsoft/GenderBias.yml | 76 ++++++----- .../styles/Microsoft/HeadingPunctuation.yml | 6 +- .github/styles/Microsoft/Hyphens.yml | 8 +- .github/styles/Microsoft/Negative.yml | 8 +- .github/styles/Microsoft/Plurals.yml | 7 + .github/styles/Microsoft/RangeFormat.yml | 13 -- .github/styles/Microsoft/RangeTime.yml | 6 +- .github/styles/Microsoft/Ranges.yml | 7 - .github/styles/Microsoft/Terms.yml | 21 +-- .github/styles/Microsoft/URLFormat.yml | 7 +- .github/styles/Microsoft/Wordiness.yml | 15 ++- .vale.ini | 2 + 17 files changed, 100 insertions(+), 221 deletions(-) delete mode 100644 .github/styles/Microsoft/ComplexWords.yml create mode 100644 .github/styles/Microsoft/Plurals.yml delete mode 100644 .github/styles/Microsoft/RangeFormat.yml delete mode 100644 .github/styles/Microsoft/Ranges.yml diff --git a/.github/styles/Microsoft/Accessibility.yml b/.github/styles/Microsoft/Accessibility.yml index 05bf927390..f5f4829392 100644 --- a/.github/styles/Microsoft/Accessibility.yml +++ b/.github/styles/Microsoft/Accessibility.yml @@ -6,20 +6,25 @@ ignorecase: true tokens: - a victim of - able-bodied - - affected by - an epileptic + - birth defect - crippled + - differently abled - disabled - dumb - handicapped - handicaps - - healthy + - healthy person + - hearing-impaired - lame - maimed + - mentally handicapped - missing a limb - mute - - normal + - non-verbal + - normal person - sight-impaired + - slow learner - stricken with - suffers from - vision-impaired diff --git a/.github/styles/Microsoft/Adverbs.yml b/.github/styles/Microsoft/Adverbs.yml index 07d98d83e3..5619f99d8c 100644 --- a/.github/styles/Microsoft/Adverbs.yml +++ b/.github/styles/Microsoft/Adverbs.yml @@ -1,5 +1,5 @@ extends: existence -message: "Consider removing '%s'." +message: "Remove '%s' if it's not important to the meaning of the statement." link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences ignorecase: true level: warning @@ -54,6 +54,7 @@ tokens: - doubtfully - dreamily - easily + - effectively - elegantly - energetically - enormously @@ -164,6 +165,7 @@ tokens: - quickly - quietly - quirkily + - quite - quizzically - randomly - rapidly diff --git a/.github/styles/Microsoft/ComplexWords.yml b/.github/styles/Microsoft/ComplexWords.yml deleted file mode 100644 index 65b7a34721..0000000000 --- a/.github/styles/Microsoft/ComplexWords.yml +++ /dev/null @@ -1,120 +0,0 @@ -extends: substitution -message: "Consider using '%s' instead of '%s'." -link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences -ignorecase: true -level: suggestion -action: - name: replace -swap: - "approximate(?:ly)?": about - abundance: plenty - accelerate: speed up - accentuate: stress - accompany: go with - accomplish: carry out|do - accorded: given - accordingly: so - accrue: add - accurate: right|exact - acquiesce: agree - acquire: get|buy - additional: more|extra - address: discuss - addressees: you - adjacent to: next to - adjustment: change - admissible: allowed - advantageous: helpful - advise: tell - aggregate: total - aircraft: plane - alleviate: ease - allocate: assign|divide - alternatively: or - alternatives: choices|options - ameliorate: improve - amend: change - anticipate: expect - apparent: clear|plain - ascertain: discover|find out - assistance: help - attain: meet - attempt: try - authorize: allow - belated: late - bestow: give - cease: stop|end - collaborate: work together - commence: begin - compensate: pay - component: part - comprise: form|include - concept: idea - concerning: about - confer: give|award - consequently: so - consolidate: merge - constitutes: forms - contains: has - convene: meet - demonstrate: show|prove - depart: leave - designate: choose - desire: want|wish - determine: decide|find - detrimental: bad|harmful - disclose: share|tell - discontinue: stop - disseminate: send|give - eliminate: end - elucidate: explain - employ: use - enclosed: inside|included - encounter: meet - endeavor: try - enumerate: count - equitable: fair - equivalent: equal - exclusively: only - expedite: hurry - facilitate: ease - females: women - finalize: complete|finish - frequently: often - identical: same - incorrect: wrong - indication: sign - initiate: start|begin - itemized: listed - jeopardize: risk - liaise: work with|partner with - maintain: keep|support - methodology: method - modify: change - monitor: check|watch - multiple: many - necessitate: cause - notify: tell - numerous: many - objective: aim|goal - obligate: bind|compel - optimum: best|most - permit: let - portion: part - possess: own - previous: earlier - previously: before - prioritize: rank - procure: buy - provide: give|offer - purchase: buy - relocate: move - solicit: request - state-of-the-art: latest - subsequent: later|next - substantial: large - sufficient: enough - terminate: end - transmit: send - utilization: use - utilize: use diff --git a/.github/styles/Microsoft/Dashes.yml b/.github/styles/Microsoft/Dashes.yml index 2894cf7229..72b05ba3e5 100644 --- a/.github/styles/Microsoft/Dashes.yml +++ b/.github/styles/Microsoft/Dashes.yml @@ -7,7 +7,7 @@ level: error action: name: edit params: - - remove - - ' ' + - trim + - " " tokens: - - '[—–]\s|\s[—–]' + - '\s[—–]\s|\s[—–]|[—–]\s' diff --git a/.github/styles/Microsoft/FirstPerson.yml b/.github/styles/Microsoft/FirstPerson.yml index 77761af883..f58dea3142 100644 --- a/.github/styles/Microsoft/FirstPerson.yml +++ b/.github/styles/Microsoft/FirstPerson.yml @@ -5,8 +5,8 @@ ignorecase: true level: warning nonword: true tokens: - - (?:^|\s)I\s - - (?:^|\s)I,\s + - (?:^|\s)I(?=\s) + - (?:^|\s)I(?=,\s) - \bI'd\b - \bI'll\b - \bI'm\b diff --git a/.github/styles/Microsoft/GenderBias.yml b/.github/styles/Microsoft/GenderBias.yml index 3d873aa31d..fc987b94e9 100644 --- a/.github/styles/Microsoft/GenderBias.yml +++ b/.github/styles/Microsoft/GenderBias.yml @@ -2,43 +2,41 @@ extends: substitution message: "Consider using '%s' instead of '%s'." ignorecase: true level: error +action: + name: replace swap: - (?:alumna|alumnus): graduate - (?:alumnae|alumni): graduates - air(?:m[ae]n|wom[ae]n): pilot(s) - anchor(?:m[ae]n|wom[ae]n): anchor(s) - authoress: author - camera(?:m[ae]n|wom[ae]n): camera operator(s) - chair(?:m[ae]n|wom[ae]n): chair(s) - congress(?:m[ae]n|wom[ae]n): member(s) of congress - door(?:m[ae]|wom[ae]n): concierge(s) - draft(?:m[ae]n|wom[ae]n): drafter(s) - fire(?:m[ae]n|wom[ae]n): firefighter(s) - fisher(?:m[ae]n|wom[ae]n): fisher(s) - fresh(?:m[ae]n|wom[ae]n): first-year student(s) - garbage(?:m[ae]n|wom[ae]n): waste collector(s) - lady lawyer: lawyer - ladylike: courteous - landlord: building manager - mail(?:m[ae]n|wom[ae]n): mail carriers - man and wife: husband and wife - man enough: strong enough - mankind: human kind - manmade: manufactured - manpower: personnel - men and girls: men and women - middle(?:m[ae]n|wom[ae]n): intermediary - news(?:m[ae]n|wom[ae]n): journalist(s) - ombuds(?:man|woman): ombuds - oneupmanship: upstaging - poetess: poet - police(?:m[ae]n|wom[ae]n): police officer(s) - repair(?:m[ae]n|wom[ae]n): technician(s) - sales(?:m[ae]n|wom[ae]n): salesperson or sales people - service(?:m[ae]n|wom[ae]n): soldier(s) - steward(?:ess)?: flight attendant - tribes(?:m[ae]n|wom[ae]n): tribe member(s) - waitress: waiter - woman doctor: doctor - woman scientist[s]?: scientist(s) - work(?:m[ae]n|wom[ae]n): worker(s) + (?:alumna|alumnus): graduate + (?:alumnae|alumni): graduates + air(?:m[ae]n|wom[ae]n): pilot(s) + anchor(?:m[ae]n|wom[ae]n): anchor(s) + authoress: author + camera(?:m[ae]n|wom[ae]n): camera operator(s) + door(?:m[ae]|wom[ae]n): concierge(s) + draft(?:m[ae]n|wom[ae]n): drafter(s) + fire(?:m[ae]n|wom[ae]n): firefighter(s) + fisher(?:m[ae]n|wom[ae]n): fisher(s) + fresh(?:m[ae]n|wom[ae]n): first-year student(s) + garbage(?:m[ae]n|wom[ae]n): waste collector(s) + lady lawyer: lawyer + ladylike: courteous + mail(?:m[ae]n|wom[ae]n): mail carriers + man and wife: husband and wife + man enough: strong enough + mankind: human kind + manmade: manufactured + manpower: personnel + middle(?:m[ae]n|wom[ae]n): intermediary + news(?:m[ae]n|wom[ae]n): journalist(s) + ombuds(?:man|woman): ombuds + oneupmanship: upstaging + poetess: poet + police(?:m[ae]n|wom[ae]n): police officer(s) + repair(?:m[ae]n|wom[ae]n): technician(s) + sales(?:m[ae]n|wom[ae]n): salesperson or sales people + service(?:m[ae]n|wom[ae]n): soldier(s) + steward(?:ess)?: flight attendant + tribes(?:m[ae]n|wom[ae]n): tribe member(s) + waitress: waiter + woman doctor: doctor + woman scientist[s]?: scientist(s) + work(?:m[ae]n|wom[ae]n): worker(s) diff --git a/.github/styles/Microsoft/HeadingPunctuation.yml b/.github/styles/Microsoft/HeadingPunctuation.yml index af04b02ebf..4954cb11ae 100644 --- a/.github/styles/Microsoft/HeadingPunctuation.yml +++ b/.github/styles/Microsoft/HeadingPunctuation.yml @@ -7,7 +7,7 @@ scope: heading action: name: edit params: - - remove - - '.?!' + - trim_right + - ".?!" tokens: - - '[a-z][.?!](?:\s|$)' + - "[a-z][.?!]$" diff --git a/.github/styles/Microsoft/Hyphens.yml b/.github/styles/Microsoft/Hyphens.yml index 90bbb5def9..7e5731c995 100644 --- a/.github/styles/Microsoft/Hyphens.yml +++ b/.github/styles/Microsoft/Hyphens.yml @@ -7,8 +7,8 @@ nonword: true action: name: edit params: - - replace - - '-' - - ' ' + - regex + - "-" + - " " tokens: - - '\s[^\s-]+ly-' + - '\b[^\s-]+ly-\w+\b' diff --git a/.github/styles/Microsoft/Negative.yml b/.github/styles/Microsoft/Negative.yml index d6ff2f2243..d73221f539 100644 --- a/.github/styles/Microsoft/Negative.yml +++ b/.github/styles/Microsoft/Negative.yml @@ -6,8 +6,8 @@ level: error action: name: edit params: - - replace - - '-' - - '–' + - regex + - "-" + - "–" tokens: - - '\s-\d+\s' + - '(?<=\s)-\d+(?:\.\d+)?\b' diff --git a/.github/styles/Microsoft/Plurals.yml b/.github/styles/Microsoft/Plurals.yml new file mode 100644 index 0000000000..1bb6660ade --- /dev/null +++ b/.github/styles/Microsoft/Plurals.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't add '%s' to a singular noun. Use plural instead." +ignorecase: true +level: error +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/s/s-es +raw: + - '\(s\)|\(es\)' diff --git a/.github/styles/Microsoft/RangeFormat.yml b/.github/styles/Microsoft/RangeFormat.yml deleted file mode 100644 index f1d736e9de..0000000000 --- a/.github/styles/Microsoft/RangeFormat.yml +++ /dev/null @@ -1,13 +0,0 @@ -extends: existence -message: "Use an en dash in a range of numbers." -link: https://docs.microsoft.com/en-us/style-guide/numbers -nonword: true -level: error -action: - name: edit - params: - - replace - - '-' - - '–' -tokens: - - '\b\d+\s?[-]\s?\d+\b' diff --git a/.github/styles/Microsoft/RangeTime.yml b/.github/styles/Microsoft/RangeTime.yml index cdd4b3346e..72d8bbfbe3 100644 --- a/.github/styles/Microsoft/RangeTime.yml +++ b/.github/styles/Microsoft/RangeTime.yml @@ -6,8 +6,8 @@ level: error action: name: edit params: - - replace - - '[-–]' - - 'to' + - regex + - "[-–]" + - "to" tokens: - '\b(?:AM|PM)\s?[-–]\s?.+(?:AM|PM)\b' diff --git a/.github/styles/Microsoft/Ranges.yml b/.github/styles/Microsoft/Ranges.yml deleted file mode 100644 index 67d9702b0f..0000000000 --- a/.github/styles/Microsoft/Ranges.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: "In most cases, use 'from' or 'through' to describe a range of numbers." -link: 'https://docs.microsoft.com/en-us/style-guide/numbers' -nonword: true -level: warning -tokens: - - '\b\d+\s?[-–]\s?\d+\b' diff --git a/.github/styles/Microsoft/Terms.yml b/.github/styles/Microsoft/Terms.yml index 7708900ebb..65fca10aaa 100644 --- a/.github/styles/Microsoft/Terms.yml +++ b/.github/styles/Microsoft/Terms.yml @@ -7,27 +7,28 @@ ignorecase: true action: name: replace swap: - '(?:agent|virtual assistant|intelligent personal assistant)': personal digital assistant - '(?:drive C:|drive C>|C: drive)': drive C - '(?:internet bot|web robot)s?': bot(s) - '(?:microsoft cloud|the cloud)': cloud - '(?:mobile|smart) ?phone': phone - '24/7': every day - 'audio(?:-| )book': audiobook - 'back(?:-| )light': backlight - 'chat ?bots?': chatbot(s) + "(?:agent|virtual assistant|intelligent personal assistant)": personal digital assistant + "(?:assembler|machine language)": assembly language + "(?:drive C:|drive C>|C: drive)": drive C + "(?:internet bot|web robot)s?": bot(s) + "(?:microsoft cloud|the cloud)": cloud + "(?:mobile|smart) ?phone": phone + "24/7": every day + "audio(?:-| )book": audiobook + "back(?:-| )light": backlight + "chat ?bots?": chatbot(s) adaptor: adapter administrate: administer afterwards: afterward alphabetic: alphabetical alphanumerical: alphanumeric + an URL: a URL anti-aliasing: antialiasing anti-malware: antimalware anti-spyware: antispyware anti-virus: antivirus appendixes: appendices artificial intelligence: AI - '(?:assembler|machine language)': assembly language caap: CaaP conversation-as-a-platform: conversation as a platform eb: EB diff --git a/.github/styles/Microsoft/URLFormat.yml b/.github/styles/Microsoft/URLFormat.yml index 82e702f981..4e24aa59fe 100644 --- a/.github/styles/Microsoft/URLFormat.yml +++ b/.github/styles/Microsoft/URLFormat.yml @@ -1,10 +1,9 @@ extends: substitution -message: "Use '%s' instead of '%s'." +message: Use 'of' (not 'for') to describe the relationship of the word URL to a resource. ignorecase: true -level: error +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/url +level: suggestion action: name: replace swap: URL for: URL of - an URL: a URL - diff --git a/.github/styles/Microsoft/Wordiness.yml b/.github/styles/Microsoft/Wordiness.yml index 22a4c932c8..8a4fea7483 100644 --- a/.github/styles/Microsoft/Wordiness.yml +++ b/.github/styles/Microsoft/Wordiness.yml @@ -2,12 +2,16 @@ extends: substitution message: "Consider using '%s' instead of '%s'." link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences ignorecase: true -level: warning +level: suggestion action: name: replace swap: - (?:give|gave) rise to: lead to + "sufficient number(?: of)?": enough + (?:extract|take away|eliminate): remove + (?:in order to|as a means to): to + (?:inform|let me know): tell (?:previous|prior) to: before + (?:utilize|make use of): use a (?:large)? majority of: most a (?:large)? number of: many a myriad of: myriad @@ -15,7 +19,7 @@ swap: all across: across all of a sudden: suddenly all of these: these - all of: all + all of(?! a sudden| these): all all-time record: record almost all: most almost never: seldom @@ -52,13 +56,14 @@ swap: continue on: continue despite the fact that: although disappear from sight: disappear + doomed to fail: doomed drag and drop: drag drag-and-drop: drag - doomed to fail: doomed due to the fact that: because during the period of: during during the time that: while emergency situation: emergency + establish connectivity: connect except when: unless excessive number: too many extend an invitation: invite @@ -74,6 +79,7 @@ swap: in a careful manner: carefully in a thoughtful manner: thoughtfully in a timely manner: timely + in addition: also in an effort to: to in between: between in lieu of: instead of @@ -106,7 +112,6 @@ swap: span across: span subsequent to: after successfully complete: complete - sufficient number (?:of)?: enough take action: act take into account: consider the question as to whether: whether diff --git a/.vale.ini b/.vale.ini index c1a4ee7cbd..8f5c215159 100644 --- a/.vale.ini +++ b/.vale.ini @@ -19,6 +19,8 @@ Vale.Spelling = YES # Disabling rules (NO) +Microsoft.Dashes = NO +Microsoft.Avoid = NO Microsoft.Contractions = NO Microsoft.Foreign = NO Microsoft.We = NO