From 03f947196bf017d714c69551e9410c9507324955 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Sun, 2 Oct 2016 11:03:37 +0100 Subject: [PATCH] contributing.md: various tweaks (#1100) - adjust whitespace & line breaks to make the markdown source more readable and consistent - remove "we"/"our", to avoid reinforcing the "us vs. them" paradigm - clarify a couple passages - remove obsolete license agreement notice, now covered by the CLA - remove redundant (and oddly specific) plea for contributions and the end of the document, since there's already one at the beginning - remove a redundant example of commit message format --- CONTRIBUTING.md | 56 ++++++++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b0384b6c9..5dfe3d6ecd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,12 +11,16 @@ To get started, sign the [Contributor License Agreement](https://cla-assistant.i The basic format of a `tldr` page is a set of concrete usage examples. Here are a few guidelines to get started: -1. Focus on the 5 or 6 most common usages. It's OK if the page doesn't cover everything; that's what `man` is for. -2. When in doubt, keep new command-line users in mind. Err on the side of clarity rather than terseness. +1. Focus on the 5 or 6 most common usages. + It's OK if the page doesn't cover everything; that's what `man` is for. +2. When in doubt, keep new command-line users in mind. + Err on the side of clarity rather than terseness. 3. Try to incorporate the spelled-out version of single-letter options in the example's description. The goal is to allow people to *understand* the syntax of the commands, not just *memorize* it. -4. Introduce options gradually, starting with the simplest commands and using more complex examples progressively. -5. Use short but descriptive values for the tokens, ex. `{{source_file}}` or `{{wallet.txt}}`. +4. Introduce options gradually, starting with the simplest command invocations, + and using more complex examples progressively. +5. Use short but descriptive values for the tokens, + ex. `{{source_file}}` or `{{wallet.txt}}`. 6. Focus on details specific to the command, and avoid explaining general UNIX concepts that could apply to any command (ex: relative/absolute paths, glob patterns/wildcards, special character escaping...). @@ -41,7 +45,7 @@ The format of each page should match the following: `command -opt1 -opt2` ``` -We actually have a linter/formatter that enforces our format. +There actually is a linter/formatter that enforces the format above. It is run automatically on every pull request, but you may install it to test your contributions locally before submitting them: @@ -54,31 +58,38 @@ For other ways to use `tldrl`, such as linting an entire directory, check out (w [`tldr tldrl`](https://github.com/tldr-pages/tldr/blob/master/pages/common/tldrl.md) ### Token syntax -User-provided values should use the `{{token}}` syntax -in order to allow clients to highlight them. -Use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) -for multi-word tokens. + +User-provided values should use the `{{token}}` syntax in order to allow `tldr` clients to highlight them. +Use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for multi-word tokens. Keep the following guidelines in mind when choosing token names: -- 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}}`. +- 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}}`. -- For any reference to paths to files or folders, use `{{path/to/}}`. For example, `ln -s {{path/to/file}} {{path/to/symlink}}`. In case of a possible reference both to a file or a folder, use `{{path/to/file_or_folder}}` +- For any reference to paths to files or folders, use `{{path/to/}}`. + For example, `ln -s {{path/to/file}} {{path/to/symlink}}`. + In case of a possible reference both to a file or a folder, use `{{path/to/file_or_folder}}` -- If a command expects the file to have a particular extension, use it. For example, `unrar x {{compressed.rar}}`. In case needs a generic extension, use `{{.ext}}`, but **only** if it helps to clarify the command. For example, here: +- If a command expects the file to have a particular extension, use it. + For example, `unrar x {{compressed.rar}}`. + In case needs a generic extension, use `{{.ext}}`, but **only** if it helps to clarify the command. + For example, here: ``` Open all the files of a given extension in the current directory with the associated application: open {{*.ext}} ``` - ... using `{{.ext}}` helps to clarify the command. But in a command like `wc -l {{file}}`, using `{{file}}` is sufficiently clear. + ... using `{{.ext}}` helps to clarify the command. + But in a command like `wc -l {{file}}`, using `{{file}}` is sufficiently clear. -- Lastly, follow the `{{path/to/}}` convention when there is a path-related command. Not when the file location is implicit. But of course, use proper judgement, keeping simplicity and user friendliness as the top priority. +- Lastly, follow the `{{path/to/}}` convention when there is a path-related command, + except when the file location is implicit. + But of course, use proper judgement, keeping simplicity and user friendliness as the top priority. -In short, make it as intuitive as possible -for the user to figure out how to use the command -and fill it in with values. +In short, choose tokens that make it as intuitive as possible +for the user to figure out how to use the command and fill it in with values. ## Submitting a pull request @@ -125,17 +136,10 @@ Examples: - `ls: add page` - `cat: fix typo` - `git-push: add --force example` - - `uname: fix -a example` ## Licensing `tldr` is licensed under the [MIT license](https://github.com/tldr-pages/tldr/blob/master/LICENSE.md). -**IMPORTANT**: By submitting a patch, you agree to license your work -under the same license as that used by the project. - -You're free to modify or redistribute the content. -That being said, but why not contribute over here? :) -Say if you wanted to have `tldr` pages in `groff` format, -why not have a client that uses [pandoc](http://johnmacfarlane.net/pandoc/) -and periodically updates straight from this repo? +Any contributions to this project are governed by the +[Contributor License Agreement](https://cla-assistant.io/tldr-pages/tldr).