Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Reorganise rules
Browse files Browse the repository at this point in the history
frankharkins committed Oct 10, 2023
1 parent 0e9bb03 commit 71b9914
Showing 9 changed files with 194 additions and 185 deletions.
15 changes: 15 additions & 0 deletions IBMQuantum/Accessibility.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
extends: substitution
message: Use '%s' rather than '%s' if referring to position in a document (for screen readers).
link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist'
level: warning
ignorecase: true
action:
name: replace
# swap maps tokens in form of bad: good
swap:
'down(?:-)?level': earlier|previous|not at the latest level
'down(?:-)?level': earlier|previous|not at the latest level
bottom: end|last
below: following
above: previous
top: start|beginning|first
File renamed without changes.
4 changes: 3 additions & 1 deletion IBMQuantum/Latin.yml
Original file line number Diff line number Diff line change
@@ -10,4 +10,6 @@ swap:
'\b(?:eg|e\.g\.)[\s,]': for example
'\b(?:ie|i\.e\.)[\s,]': that is
'\betc\.': and so on
'\bvs\.': versus
'\bvs\.': compared to
via: through
versus: compared to
8 changes: 8 additions & 0 deletions IBMQuantum/Recommend.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
extends: existence
message: "Don't use '%s'; we should not recommend to users."
link: 'https://github.com/IBM/ibm-quantum-style-guide/issues/22' # TODO
ignorecase: true
scope: sentence
level: warning
tokens:
- recommend
271 changes: 96 additions & 175 deletions IBMQuantum/Terms.yml
Original file line number Diff line number Diff line change
@@ -1,183 +1,104 @@
extends: substitution
message: Use '%s' rather than '%s'
message: Use '%s' rather than '%s' for consistency across IBM Quantum.
link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist'
level: warning
ignorecase: true
action:
name: replace
# swap maps tokens in form of bad: good
swap:
'(?:Ctrl|control)-click': press Ctrl and click
'a lot(?: of)?': many|much
'backward(?:-)?compatible': compatible with earlier versions
'down(?:-)?level': earlier|previous|not at the latest level
'mash(?: )?up': create
'pop-up (?:blocker|killer)': software to block pop-up ad windows
're(?:-)?occur': recur
'sort(?:-|/)?merge': sort|merge

bottom: end|last
below: following
above: previous
top: start|beginning|first
a number of: several
abort: cancel|stop
administrate: administer
all caps: uppercase
and/or: a or b|a, b, or both
as long as: if|provided that
as per: according to|as|as in
back-level: earlier|previous|not at the latest level
Big Blue: IBM
blink: flash
blue screen of death: stop error
breadcrumbing: breadcrumb trail
canned: preplanned|preconfigured|predefined
case insensitive: not case-sensitive
catastrophic error: unrecoverable error
CBE: Common Base Event
CBTS: CICS BTS|BTS
cold boot: hardware restart
cold start: hardware restart
comes with: includes
componentization: component-based development|component model|component architecture|shared components
componentize: develop components
comprised of: consist of
connect with: connect to
context menu: menu|pop-up menu
contextual help: help|context-sensitive help
crash: fail|lock up|stop|stop responding
CRUD: create retrieve update and delete
customer: client
datum: data
debuggable: debug
deconfigure: unconfigure
deinstall: uninstall
deinstallation: uninstallation
demilitarized zone: DMZ
demo: demonstration
depress: press|type
deregister: unregister
desire: want|required
destroy: delete from the database
dismount: demount|unmount|remove
downgrade: upgrade|fallback|fall back|rollback|roll back
downward compatible: compatible with earlier versions
drag and drop: drag
drill up: navigate
e-fix: fix|interim fix
eFix: fix|interim fix
end user: user
end-user interface: graphical interface|interface
EUI: graphical user interface|interface
expose: display|show|make available
fill in: complete|enter|specify
fixed disk drive: hard disk drive
flavor: version|method
floppy disk: diskette|diskette drive
floppy drive: diskette|diskette drive
floppy: diskette|diskette drive
forward compatible: compatible with later versions
gzip: compress
gzipped: archive|compressed file
hard drive: hard disk|hard disk drive
hard file: hard disk|hard disk drive
hence: therefore
i-fix: interim fix
i-Fix: interim fix
IBM's: IBM's|IBM's AIX
ifix: interim fix
iFix: interim fix
in order to: to
in other words: for example|that is
in spite of: regardless of|despite
in the event: in case|if|when
inactivate: deactivate
information on: information about
information technology: IT
instead of: rather than
insure: ensure
Internet address: IP address|URL|Internet email address|web address
irrecoverable: unrecoverable
jar: compress|archive
keep in mind: remember
launch: start|open
left-hand: left
leverage: use
line cord: power cable|power cord
main directory: root directory
memory stick: USB flash drive
microcomputer: PC
motherboard: system board
mouse over: point to|move the mouse pointer over|Mouse|mouse over
network-centric computing: network computing
non-English: in languages other than English|non-English-language
nonrecoverable: unrecoverable
notion: concept
off-premise: on-premises|off-premises|onsite|offsite
offline storage: auxiliary storage
okay: OK
on ramp: access method
on the fly: dynamically|as needed|in real time|immediately
on the other hand: however|alternatively|conversely
on-premise: on-premises|off-premises|onsite|offsite
on-ramp: access method
pain point: challenge|concern|difficulty|issue
parent task: parent process
patch: fix|test fix|interim fix|fix pack|program temporary fix
perimeter network: DMZ
power down: turn on|turn off
power off: turn on|turn off
power on: turn on|turn off
preload: preinstall|preinstalled
preloaded: preinstall|preinstalled
prepend: add a prefix to
prior to: before
recommend: suggest
retry: retry|try again
right double-click: double right-click
right-hand: right
rule of thumb: rule
sanity check: test|evaluate
secondary storage: auxiliary storage
selection button: left mouse button
serial database: nonpartitioned database environment
set-up: setup
shift-click: press Shift and click
ship: include|included
Simple Object Access Protocol: SOAP
single quote mark: single quotation mark
single quote: single quotation mark
SME routine: session management exit routine
start up: start
sunset: withdraw from service|withdraw from marketing|discontinue|no longer support
switch off: power on|turn on|power off|turn off
switch on: power on|turn on|power off|turn off
tar: compress|archive
tarball: tar file
terminate: end|stop
thru: through
thumbstick: USB flash drive
thus: therefore
toggle off: toggle
tooling: tools
touchscreen: touch-sensitive screen
transparent: indiscernible|not visible
typo: typing error|typographical error
uncheck: clear
uncompress: decompress
undeploy: remove|withdraw
unjar: extract
unselect: clear|deselect
untar: extract
unzip: unzip
upward compatible: compatible with later versions
utilize: use
versus: compared to
via: through
warning notice: attention notice
web-enable: enable for the web
webinar: webinar|webcast|web seminar|web-based event
wish: want
zero out: zero
zip: zip|compress
'backward(?:-)?compatible': compatible with earlier versions
'mash(?: )?up': create
'pop-up (?:blocker|killer)': software to block pop-up ad windows
're(?:-)?occur': recur
'sort(?:-|/)?merge': sort|merge
abort: cancel|stop
administrate: administer
all caps: uppercase
and/or: a or b|a, b, or both
as per: according to|as|as in
case insensitive: not case-sensitive
catastrophic error: unrecoverable error
comes with: includes
componentization: component-based development|component model|component architecture|shared components
componentize: develop components
connect with: connect to
crash: fail|lock up|stop|stop responding
CRUD: create retrieve update and delete
customer: client
datum: data
debuggable: debug
deconfigure: unconfigure
deinstall: uninstall
deinstallation: uninstallation
demo: demonstration
deregister: unregister
desire: want|required
destroy: delete (data)
dismount: demount|unmount|remove
downgrade: upgrade|fallback|fall back|rollback|roll back
downward compatible: compatible with earlier versions
e-fix: fix|interim fix
eFix: fix|interim fix
end user: user
end-user interface: graphical interface|interface
EUI: graphical user interface|interface
expose: display|show|make available
flavor: version|method
forward compatible: compatible with later versions
gzip: compress
gzipped: archive|compressed file
hard drive: hard disk|hard disk drive
hard file: hard disk|hard disk drive
i-fix: interim fix
ifix: interim fix
inactivate: deactivate
information on: information about
information technology: IT
internet address: IP address|URL|Internet email address|web address
irrecoverable: unrecoverable
jar: compress|archive
line cord: power cable|power cord
main directory: root directory
memory stick: USB flash drive
microcomputer: PC
motherboard: system board
network-centric computing: network computing
non-English: in languages other than English|non-English-language
nonrecoverable: unrecoverable
notion: concept
off-premise: on-premises|off-premises|onsite|offsite
okay: OK
on ramp: access method
on-premise: on-premises|off-premises|onsite|offsite
on-ramp: access method
parent task: parent process
patch: fix|test fix|interim fix|fix pack|program temporary fix
preload: preinstall|preinstalled
preloaded: preinstall|preinstalled
sanity check: test|evaluate
secondary storage: auxiliary storage
serial database: nonpartitioned database environment
set-up: setup
ship: include|included
single quote mark: single quotation mark
single quote: single quotation mark
start up: start
sunset: withdraw from service|withdraw from marketing|discontinue|no longer support
tar: compress|archive
tarball: tar file
thru: through
thumbstick: USB flash drive
tooling: tools
typo: typing error
uncompress: decompress
undeploy: remove|withdraw
unjar: extract
untar: extract
unzip: unzip
upward compatible: compatible with later versions
warning notice: attention notice
web-enable: enable for the web
webinar: webinar|webcast|web seminar|web-based event
wish: want
zero out: zero
29 changes: 29 additions & 0 deletions IBMQuantum/UIConsistency.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
extends: substitution
message: Use '%s' rather than '%s' if writing about user interfaces.
link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist'
level: warning
ignorecase: true
action:
name: replace
# swap maps tokens in form of bad: good
swap:
'(?:Ctrl|control)-click': press Ctrl and click
blink: flash
breadcrumbing: breadcrumb trail
context menu: menu|pop-up menu
contextual help: help|context-sensitive help
depress: press|type
drag and drop: drag
drill up: navigate
fill in: complete|enter|specify
launch: start|open
left-hand: left
mouse over: point to|move the mouse pointer over|Mouse|mouse over
right double-click: double right-click
right-hand: right
selection button: left mouse button
shift-click: press Shift and click
switch off: turn off
switch on: turn on
uncheck: clear
unselect: clear|deselect
29 changes: 29 additions & 0 deletions IBMQuantum/Wordiness.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
extends: substitution
message: Try '%s' rather than '%s'.
link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist'
level: warning
ignorecase: true
action:
name: replace
# swap maps tokens in form of bad: good
swap:
'a lot(?: of)?': many|much
a number of: several
as long as: if|provided that
comprised of: consist of
hence: therefore
in order to: to
in other words: for example|that is
in spite of: regardless of|despite
in the event: in case|if|when
keep in mind: remember
leverage: use
on the fly: dynamically|as needed|in real time|immediately
on the other hand: however|alternatively|conversely
pain point: challenge|concern|difficulty|issue
prepend: add a prefix to
prior to: before
rule of thumb: rule
terminate: end|stop
thus: therefore
utilize: use
17 changes: 9 additions & 8 deletions features/rules.feature
Original file line number Diff line number Diff line change
@@ -4,17 +4,17 @@ Feature: Rules
When I test "Terms"
Then the output should contain exactly:
"""
test.md:3:13:IBMQuantum.Terms:Use 'end' or 'last' rather than 'bottom'
test.md:5:11:IBMQuantum.Terms:Use 'several' rather than 'a number of'
test.md:3:13:IBMQuantum.Accessibility:Use 'end' or 'last' rather than 'bottom' if referring to position in a document (for screen readers).
test.md:5:11:IBMQuantum.Wordiness:Try 'several' rather than 'a number of'.
test.md:11:10:IBMQuantum.Spelling:Unknown word 'algorihm'; fix or add to dictionary.
test.md:15:24:IBMQuantum.Terms:Use 'following' rather than 'below'
test.md:15:24:IBMQuantum.Accessibility:Use 'following' rather than 'below' if referring to position in a document (for screen readers).
test.md:19:29:IBMQuantum.However:Double-check your punctuation around 'however' (see github.com/IBM/ibm-quantum-style-guide/issues/10 for more information).
test.md:23:16:IBMQuantum.However:Double-check your punctuation around 'however' (see github.com/IBM/ibm-quantum-style-guide/issues/10 for more information).
test.md:25:1:IBMQuantum.Politeness:Don't use 'Please'
test.md:27:1:IBMQuantum.CringeWords:Don't use 'We understand that'
test.md:27:36:IBMQuantum.Terms:Use 'use' rather than 'utilize'
test.md:27:75:IBMQuantum.CringeWords:Don't use 'end users'
test.md:27:90:IBMQuantum.CringeWords:Don't use 'we encourage you'
test.md:27:1:IBMQuantum.BestPractice:Don't use 'We understand that'
test.md:27:36:IBMQuantum.Wordiness:Try 'use' rather than 'utilize'.
test.md:27:75:IBMQuantum.BestPractice:Don't use 'end users'
test.md:27:90:IBMQuantum.BestPractice:Don't use 'we encourage you'
test.md:29:12:IBMQuantum.Links:Link names should make sense without context; change "link" to something more descriptive.
"""

@@ -33,9 +33,10 @@ Feature: Rules
When I test "Latin"
Then the output should contain exactly:
"""
test.md:1:21:IBMQuantum.Latin:Use 'through' instead of 'via'.
test.md:3:10:IBMQuantum.Latin:Use 'and so on' instead of 'etc.'.
test.md:5:31:IBMQuantum.Latin:Use 'that is' instead of 'i.e.,'.
test.md:7:6:IBMQuantum.Latin:Use 'versus' instead of 'vs.'.
test.md:7:6:IBMQuantum.Latin:Use 'compared to' instead of 'vs.'.
"""

Scenario: Capitalization
6 changes: 5 additions & 1 deletion fixtures/Terms/.vale.ini
Original file line number Diff line number Diff line change
@@ -5,7 +5,11 @@ MinAlertLevel = suggestion
[*.md]
IBMQuantum.Spelling = YES
IBMQuantum.Terms = YES
IBMQuantum.CringeWords = YES
IBMQuantum.Accessibility = YES
IBMQuantum.UIConsistency = YES
IBMQuantum.Wordiness = YES
IBMQuantum.Recommend = YES
IBMQuantum.BestPractice = YES
IBMQuantum.Politeness = YES
IBMQuantum.However = YES
IBMQuantum.Links = YES

0 comments on commit 71b9914

Please sign in to comment.