ctome
/
tldr
mirror of https://github.com/CrimsonTome/tldr.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
tldr/CONTRIBUTING.md

101 lines
4.4 KiB
Markdown
Raw Normal View History

New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
# Contributing
add badges to contributing.md as [discussed in Gitter](https://gitter.im/tldr-pages/tldr?at=57ee0623b0ff456d3ad23195).
2016-10-02 11:08:44 +01:00
[![Gitter chat][gitter-image]][gitter-url]
[![Merged PRs][prs-merged-image]][prs-merged-url]
[![Issue stats][issuestats-image]][issuestats-url]
[![GitHub contributors][contributors-image]][contributors-url]
[![CLA assistant][cla-assistant-image]][cla-assistant-url]
[![license][license-image]][license-url]
[gitter-url]: https://gitter.im/tldr-pages/tldr
[gitter-image]: https://badges.gitter.im/tldr-pages/tldr.svg
[prs-merged-url]: https://github.com/tldr-pages/tldr/pulls?q=is:pr+is:merged
[prs-merged-image]: https://img.shields.io/github/issues-pr-closed-raw/tldr-pages/tldr.svg?label=merged+PRs
[issuestats-url]: http://isitmaintained.com/project/tldr-pages/tldr
[issuestats-image]: http://isitmaintained.com/badge/resolution/tldr-pages/tldr.svg
[contributors-url]: https://github.com/tldr-pages/tldr/graphs/contributors
[contributors-image]: https://img.shields.io/github/contributors/tldr-pages/tldr.svg
[cla-assistant-url]: https://cla-assistant.io/tldr-pages/tldr
[cla-assistant-image]: https://cla-assistant.io/readme/badge/tldr-pages/tldr
[license-url]: https://github.com/tldr-pages/tldr/blob/master/LICENSE.md
[license-image]: https://img.shields.io/github/license/tldr-pages/tldr.svg
link to GOVERNANCE.md from README.md and CONTRIBUTING.md
2017-12-27 23:33:55 +00:00
Contributions to the tldr-pages project are [most welcome](GOVERNANCE.md)!
All `tldr` pages are stored in Markdown right here on GitHub.
add subsections to "submit a PR" section (#974) * add subsections to "submit a PR" section this allows the reader to visually separate the instructions and makes the longer git-command section less prone to trigger a TLDR (heh) when reading this part. also, line wrapping tweaks, split a paragraph into two, and reword a couple passages for clarity * compact the list of git commands
2016-07-26 10:32:22 +01:00
Just open an issue or send a pull request and we'll incorporate it as soon as possible.
fix link to CLA (#1367) the cla-assistant link leads to a page requesting the user to sign it, which may not be as friendly since prospective contributors may want to simply read the CLA without a prompt to sign it.
2017-05-06 11:41:39 +01:00
To get started, please [sign](https://cla-assistant.io/tldr-pages/tldr) the
[Contributor License Agreement](https://gist.github.com/waldyrious/e50feec13683e565769fbd58ce503d4e).
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
CONTRIBUTING: greatly simplify the PR instructions (#962) * CONTRIBUTING: greatly simplify the PR instructions plus some wording tweaks here and there * improve instructions to use tldrl * brace expansion is not as common in the wild removing it keeps the examples of unix features to a manageable/readable 3 * use actual commands in the git section * use only one-liners on the git section * add subsection header for commit message * slight reword of licensing note
2016-07-24 08:05:21 +01:00
*Note*: when submitting a new command, don't forget to check if there's already a pull request in progress for it.
Update CONTRIBUTING.md Explained the use of the Makefile to setup the git pre-commit hook that rebuilds the index.
2015-04-12 20:54:27 +01:00
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
## Guidelines
CONTRIBUTING: greatly simplify the PR instructions (#962) * CONTRIBUTING: greatly simplify the PR instructions plus some wording tweaks here and there * improve instructions to use tldrl * brace expansion is not as common in the wild removing it keeps the examples of unix features to a manageable/readable 3 * use actual commands in the git section * use only one-liners on the git section * add subsection header for commit message * slight reword of licensing note
2016-07-24 08:05:21 +01:00
The basic format of a `tldr` page is a set of concrete usage examples.
Edited CONTRIBUTING.md to reflect final convention.
2016-01-07 19:53:19 +00:00
Here are a few guidelines to get started:
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
CONTRIBUTING.md: max number of commands per page as discussed in #1149
2016-11-19 17:16:19 +00:00
1. Try to keep pages at around 5 examples. Pages can be longer if needed, but don't exceed 8 examples.
Remember, it's OK if the page doesn't cover everything; that's what `man` is for.
contributing.md: adjust line-wrapping
2016-10-14 19:19:37 +01:00
2. When in doubt, keep new command-line users in mind. Err on the side of clarity rather than terseness.
For example, commands that require `sudo` should include it directly in the examples.
add subsections to "submit a PR" section (#974) * add subsections to "submit a PR" section this allows the reader to visually separate the instructions and makes the longer git-command section less prone to trigger a TLDR (heh) when reading this part. also, line wrapping tweaks, split a paragraph into two, and reword a couple passages for clarity * compact the list of git commands
2016-07-26 10:32:22 +01:00
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.
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
2016-10-02 11:03:37 +01:00
4. Introduce options gradually, starting with the simplest command invocations,
and using more complex examples progressively.
CONTRIBUTING: streamline token guidelines (#1161) - moved one entry from the general guidelines, since now there's a specific section for tokens; - reordered and numbered the entries, for clarity and ease of reference - rewrote some passages for clarity and conciseness.
2016-11-20 11:35:49 +00:00
5. Focus on details specific to the command, and avoid explaining general UNIX concepts that could apply to any command
add subsections to "submit a PR" section (#974) * add subsections to "submit a PR" section this allows the reader to visually separate the instructions and makes the longer git-command section less prone to trigger a TLDR (heh) when reading this part. also, line wrapping tweaks, split a paragraph into two, and reword a couple passages for clarity * compact the list of git commands
2016-07-26 10:32:22 +01:00
(ex: relative/absolute paths, glob patterns/wildcards, special character escaping...).
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
Extract STYLEGUIDE.md from CONTRIBUTING.md
2017-10-28 11:24:15 +01:00
These are all guidelines, not strict rules.
Use proper judgement, keeping simplicity and user-friendliness as the top priority.
When in doubt, have a look at a few existing pages :).
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
## Markdown format
Extract STYLEGUIDE.md from CONTRIBUTING.md
2017-10-28 11:24:15 +01:00
As a quick reference, the format of each page should match the following template:
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
```
# command-name
Edited CONTRIBUTING.md to reflect final convention.
2016-01-07 19:53:19 +00:00
> Short, snappy description.
small tweaks to CONTRIBUTING.md
2016-01-08 02:01:59 +00:00
> Preferably one line; two are acceptable if necessary.
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
Edited CONTRIBUTING.md to reflect final convention.
2016-01-07 19:53:19 +00:00
- Example description:
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
rework/expand - merge do's and don'ts, since they had mostly the same advice - move token formatting info to the guideline section and the markdown section, as appropriate - tweak spelling and fix a couple typos - fix options vs. values in the formatting example, and add a token there.
2015-08-25 01:16:26 +01:00
`command -opt1 -opt2 -arg1 {{arg_value}}`
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
Edited CONTRIBUTING.md to reflect final convention.
2016-01-07 19:53:19 +00:00
- Example description:
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
rework/expand - merge do's and don'ts, since they had mostly the same advice - move token formatting info to the guideline section and the markdown section, as appropriate - tweak spelling and fix a couple typos - fix options vs. values in the formatting example, and add a token there.
2015-08-25 01:16:26 +01:00
`command -opt1 -opt2`
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
```
Extract STYLEGUIDE.md from CONTRIBUTING.md
2017-10-28 11:24:15 +01:00
For more detailed page formatting guidelines,
Fix incorrect link to style guide
2017-11-29 06:11:28 +00:00
refer to the [style guide](contributing-guides/style-guide.md).
add subsections to "submit a PR" section (#974) * add subsections to "submit a PR" section this allows the reader to visually separate the instructions and makes the longer git-command section less prone to trigger a TLDR (heh) when reading this part. also, line wrapping tweaks, split a paragraph into two, and reword a couple passages for clarity * compact the list of git commands
2016-07-26 10:32:22 +01:00
Improve Contributing Guidelines: - mention feature branches - have detailed workflow to work with pull requests - move it to the bottom - add link to license - some minor fixes
2015-12-29 00:36:49 +00:00
## Submitting a pull request
add subsections to "submit a PR" section (#974) * add subsections to "submit a PR" section this allows the reader to visually separate the instructions and makes the longer git-command section less prone to trigger a TLDR (heh) when reading this part. also, line wrapping tweaks, split a paragraph into two, and reword a couple passages for clarity * compact the list of git commands
2016-07-26 10:32:22 +01:00
The easiest way to submit a change is to just edit the page directly on the Github interface.
CONTRIBUTING: greatly simplify the PR instructions (#962) * CONTRIBUTING: greatly simplify the PR instructions plus some wording tweaks here and there * improve instructions to use tldrl * brace expansion is not as common in the wild removing it keeps the examples of unix features to a manageable/readable 3 * use actual commands in the git section * use only one-liners on the git section * add subsection header for commit message * slight reword of licensing note
2016-07-24 08:05:21 +01:00
Check out the step-by-step instructions (with screenshots) on
[Github Help](https://help.github.com/articles/editing-files-in-another-user-s-repository/).
Improve Contributing Guidelines: - mention feature branches - have detailed workflow to work with pull requests - move it to the bottom - add link to license - some minor fixes
2015-12-29 00:36:49 +00:00
docs overhaul: move git cli instructions to a separate file
2017-11-27 18:43:52 +00:00
Alternatively, you can do most of the process
[using git on the command line](contributing-guides/git-terminal.md).
Added line on Travis
2016-01-24 22:37:37 +00:00
CONTRIBUTING: greatly simplify the PR instructions (#962) * CONTRIBUTING: greatly simplify the PR instructions plus some wording tweaks here and there * improve instructions to use tldrl * brace expansion is not as common in the wild removing it keeps the examples of unix features to a manageable/readable 3 * use actual commands in the git section * use only one-liners on the git section * add subsection header for commit message * slight reword of licensing note
2016-07-24 08:05:21 +01:00
### Commit message
Improve Contributing Guidelines: - mention feature branches - have detailed workflow to work with pull requests - move it to the bottom - add link to license - some minor fixes
2015-12-29 00:36:49 +00:00
CONTRIBUTING: greatly simplify the PR instructions (#962) * CONTRIBUTING: greatly simplify the PR instructions plus some wording tweaks here and there * improve instructions to use tldrl * brace expansion is not as common in the wild removing it keeps the examples of unix features to a manageable/readable 3 * use actual commands in the git section * use only one-liners on the git section * add subsection header for commit message * slight reword of licensing note
2016-07-24 08:05:21 +01:00
For the commit message, use the following format:
Improve Contributing Guidelines
2016-01-03 10:01:16 +00:00
CONTRIBUTING: greatly simplify the PR instructions (#962) * CONTRIBUTING: greatly simplify the PR instructions plus some wording tweaks here and there * improve instructions to use tldrl * brace expansion is not as common in the wild removing it keeps the examples of unix features to a manageable/readable 3 * use actual commands in the git section * use only one-liners on the git section * add subsection header for commit message * slight reword of licensing note
2016-07-24 08:05:21 +01:00
<command>: type of change
Improve Contributing Guidelines: - mention feature branches - have detailed workflow to work with pull requests - move it to the bottom - add link to license - some minor fixes
2015-12-29 00:36:49 +00:00
CONTRIBUTING: greatly simplify the PR instructions (#962) * CONTRIBUTING: greatly simplify the PR instructions plus some wording tweaks here and there * improve instructions to use tldrl * brace expansion is not as common in the wild removing it keeps the examples of unix features to a manageable/readable 3 * use actual commands in the git section * use only one-liners on the git section * add subsection header for commit message * slight reword of licensing note
2016-07-24 08:05:21 +01:00
Examples:
Update Contribution guidelines and PR template (#2575)
2018-11-13 23:39:53 +00:00
- For a new page addition: `ls: add page`
- For a page edit: `cat: fix typo`, `git-push: add --force example`
- For a new translation of an existing page: `cp: add Tamil translation`
- For related changes to several pages: `grep, find, locate: synchronize format of wildcards`
Improve Contributing Guidelines: - mention feature branches - have detailed workflow to work with pull requests - move it to the bottom - add link to license - some minor fixes
2015-12-29 00:36:49 +00:00
## Licensing
CONTRIBUTING: greatly simplify the PR instructions (#962) * CONTRIBUTING: greatly simplify the PR instructions plus some wording tweaks here and there * improve instructions to use tldrl * brace expansion is not as common in the wild removing it keeps the examples of unix features to a manageable/readable 3 * use actual commands in the git section * use only one-liners on the git section * add subsection header for commit message * slight reword of licensing note
2016-07-24 08:05:21 +01:00
`tldr` is licensed under the [MIT license](https://github.com/tldr-pages/tldr/blob/master/LICENSE.md).
New README & CONTRIBUTING that apply to pages only
2014-03-04 12:39:34 +00:00
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
2016-10-02 11:03:37 +01:00
Any contributions to this project are governed by the
[Contributor License Agreement](https://cla-assistant.io/tldr-pages/tldr).