contributing-guides/style-guide: add block device rules (#5036)

This commit is contained in:
Agno94 2021-03-29 14:21:55 +02:00 committed by GitHub
parent 9785140d65
commit a108e73ce3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -64,6 +64,8 @@ Keep the following guidelines in mind when choosing tokens:
But in a command like `wc -l {{file}}`, using `{{file}}` (without extension) is sufficient.
7. If the example is clearer with an actual value rather than a generic placeholder, use the actual value.
For example, use `iostat {{2}}` rather than `iostat {{interval_in_secs}}`.
8. If a command performs irreversible changes to a file system or to user's devices, then write every example in a way that they cannot be unmindfully copy-pasted by the user.
For example, instead of `ddrescue --force --no-scrape /dev/sda /dev/sdb` write `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}` and use the `{{/dev/sdXY}}` placeholder for *block devices* instead of `/dev/sda1`.
In general, tokens should make it as intuitive as possible
to figure out how to use the command and fill it in with values.