diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8f7358b57..c2d386272 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,8 @@ [license-url]: https://github.com/tldr-pages/tldr/blob/master/LICENSE.md [license-image]: https://img.shields.io/github/license/tldr-pages/tldr.svg -Contributions are most welcome! All `tldr` pages are stored in Markdown right here on GitHub. +Contributions to the tldr-pages project are [most welcome](GOVERNANCE.md)! +All `tldr` pages are stored in Markdown right here on GitHub. Just open an issue or send a pull request and we'll incorporate it as soon as possible. To get started, please [sign](https://cla-assistant.io/tldr-pages/tldr) the [Contributor License Agreement](https://gist.github.com/waldyrious/e50feec13683e565769fbd58ce503d4e). diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 000000000..fa1f5874f --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,126 @@ +# Project governance + +The tldr-pages project strives to have an **open**, **welcoming**, +and [**non-hierarchical**](https://en.wikipedia.org/wiki/Flat_organization) +governance structure. + +To that end, this document describes the principles +that guide the self-management of the project. +By having them written down explicitly, and open to scrutiny, +the entire community can read, apply, improve and adapt them as needed, +with no central authority. + + +## I. Participation and community interactions + +- **All contributions are welcome**, + [no matter how small](https://github.com/kentcdodds/all-contributors). + The tldr-pages project is a + [do-ocracy](https://communitywiki.org/wiki/DoOcracy), + so don't hesitate to get involved + — we're happy to welcome you into the community! + Please take a look at [CONTRIBUTING.md](CONTRIBUTING.md) + to get started. + +- **All discussions should be respectful and cordial**. + Avoid making assumptions about the others' intentions, + and make your own intentions clear. + When in doubt, provide additional context, or ask for clarification. + Remember, it's very hard to convey meaning on a purely written medium, + especially between people from different cultures, technical backgrounds, + English proficiency levels, etc. + +- **All communications are public**. + There are no permanent private channels + where maintainers discuss "internal" matters. + Occasional private chat or email messages may be exchanged, + e.g. when setting up services that require passwords, + but otherwise all communications that impact the project + will either happen in issue and PR discussions, + or in the [Gitter chat room](https://gitter.im/tldr-pages/tldr) + (which is open to all, and publicly logged). + +- **All decisions are made by community consensus**. + This does not mean there has to be unanimity, + nor that decisions result from vote counts. + What it means is that + every interested member of the community is welcome to voice their thoughts, + and incompatible positions are ideally resolved with involved participants + either agreeing with the final decision, or voluntarily + [consenting](https://en.wikipedia.org/wiki/Sociocracy#Consent_vs._consensus) + to it as "good enough for now, safe enough to try". + + +## II. Role transitions + +The following guidelines aim to keep the project vibrant and responsive, +by ensuring a **smooth transition flow between community roles** — +from newcomer, to occasional contributor, to regular contributor, to maintainer. +This way, the project should be able to adapt dynamically and flexibly +to the natural variations in availability and interest of its contributors, +improving long-term resilience, reducing the risk of burnout, and avoiding +[single points of failure](https://en.wikipedia.org/wiki/Bus_factor). + +To this end, rather than _assigning_ roles and tasks to people, +these guidelines aim to **recognize the work that people already do**. +Everyone is therefore encouraged to get involved +and contribute to the project in whatever way they prefer, +and we will strive to **get barriers out of the way** of these contributions. + +To ensure that these role transitioning processes are +straightforward, transparent, predictable, and impartial, +the metrics used are objective, easy to check, and explicitly described below. +(That's not to say they're hard-set rules: +exceptions can always be considered, via open community discussion.) + +- **Regular contributors should be added as collaborators in the repository.** + Specifically: once a contributor has had _5 pull requests merged_ + on a repository under the tldr-pages organization, + they should be invited to become + a **collaborator** in that repository. + This means they will be able to push commits to that repository, + as well as merge PRs, label and close issues, among other things. + +- **Collaborators who perform maintenance tasks should be made org members.** + (Maintenance work is understood as facilitating contributions by other people, + which in this project consists primarily of reviewing and/or merging PRs.) + Specifically: once a repository collaborator has _merged at least 10 PRs_ + and submitted at least _5 non-trivial reviews to PRs_ + (either the same or different ones) + they should be invited to become a + [**member**](https://github.com/orgs/tldr-pages/people) + of the tldr-pages organization. + This means they will be able to + push commits to all of the organization's repositories, + merge PRs, label and close issues, among other things. + _Note_: All members of the tldr-pages organization + must make their membership public. + +- **Maintainers who have been helping out for a while should become org owners.** + Specifically: members of the tldr-pages organization + who remain _active for at least 6 months_ + should be invited to become an + [**owner**](https://help.github.com/articles/permission-levels-for-an-organization/). + of the tldr-pages organization. + This means they will be able to add people to the organization, + manage all the organization's repositories, configure integrations, etc. + They should also be added to the list of current maintainers + in the [MAINTAINERS.md](MAINTAINERS.md) file. + +- **These roles are temporary, and that's OK.** + People's interests and availability naturally change over time, + so the project should regularly update the list of people in each role, + in order to accurately reflect the active team managing the project + (and to avoid conveying an undue sense of obligation + on people whose priorities have shifted.) + Specifically: If an organization member becomes _inactive for over 6 months_, + their membership status should be equally deactivated + and their name added to the list of former maintainers + in the MAINTAINERS.md file. + (They should nevertheless remain as collaborators + in the repositories on which they have been active in the past.) + Again, this is and merely a reflection + of their actual involvement with the project, + not a demotion or punishment. + Indeed, if they return to active participation in the project, + they should be added back to the organization, to reflect that fact. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 000000000..a6e10e08c --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,20 @@ +## Current maintainers + +The following people are the current owners of the tldr-pages organization, +and have admin access to all of its repositories. + +- Romain Prieto `` (@rprieto) +- Igor Shubovych `` (@igorshubovych) +- Ruben Vereecken `` (@rubenvereecken) +- Waldir Pimenta `` (@waldyrious) +- Felix Yan `` (@felixonmars) +- Leandro Ostera `` (@ostera) +- Agniva De Sarker `` (@agnivade) +- Starbeamrainbowlabs `` (@sbrl) + +## Past maintainers + +The following people are former maintainers of the tldr-pages project, +who have moved on to other projects. +Their contributions and dedication have ensured the success of the tldr project, +and for that they'll always be appreciated. diff --git a/README.md b/README.md index 7ba021114..87389e14b 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,9 @@ Maybe it doesn't help that the first option explained in `man tar` is: and usually not even then as the default block size of 20 records (10240 bytes) is very common. ``` -Surely people could benefit from simplified man pages focused on practical examples. How about: +Surely people could benefit from simplified man pages +focused on practical examples. +How about: ![tldr screenshot](screenshot.png) @@ -62,34 +64,58 @@ You can access these pages on your computer using one of the following clients: - Bash clients: - [tldr](https://github.com/raylee/tldr) - [tldr-bash-client](https://github.com/pepa65/tldr-bash-client) -- [C++ client](https://github.com/tldr-pages/tldr-cpp-client): `brew install tldr` -- [Crystal client](https://github.com/porras/tlcr): `brew install porras/tap/tlcr` -- [Dart client](https://github.com/hterkelsen/tldr): `pub global activate tldr` -- [Elixir client](https://github.com/edgurgel/tldr_elixir_client) (binaries not yet available) -- [Emacs client](https://github.com/kuanyui/tldr.el), available on [MELPA](https://github.com/melpa/melpa) +- [C++ client](https://github.com/tldr-pages/tldr-cpp-client): + `brew install tldr` +- [Crystal client](https://github.com/porras/tlcr): + `brew install porras/tap/tlcr` +- [Dart client](https://github.com/hterkelsen/tldr): + `pub global activate tldr` +- [Elixir client](https://github.com/edgurgel/tldr_elixir_client) + (binaries not yet available) +- [Emacs client](https://github.com/kuanyui/tldr.el), available on + [MELPA](https://github.com/melpa/melpa) - Go clients: - - [github.com/pranavraja/tldr](https://github.com/pranavraja/tldr): `go get github.com/pranavraja/tldr` (or [platform binaries](https://github.com/pranavraja/tldr/releases)) - - [4d63.com/tldr](https://4d63.com/tldr): `go get 4d63.com/tldr` or `brew install 4d63/tldr/tldr` (or [platform binaries](https://github.com/leighmcculloch/tldr/releases)) + - [github.com/pranavraja/tldr](https://github.com/pranavraja/tldr): + `go get github.com/pranavraja/tldr` + (or [platform binaries](https://github.com/pranavraja/tldr/releases)) + - [4d63.com/tldr](https://4d63.com/tldr): + `go get 4d63.com/tldr` or `brew install 4d63/tldr/tldr` + (or [platform binaries](https://github.com/leighmcculloch/tldr/releases)) - iOS clients: - - [tldr-man-page](https://github.com/freesuraj/TLDR), available on [App Store](https://appsto.re/sg/IQ0-_.i) - - [tldr-pages](https://github.com/mflint/ios-tldr-viewer), available on [App Store](https://itunes.apple.com/us/app/tldt-pages/id1071725095?ls=1&mt=8) -- [Haskell client](https://github.com/psibi/tldr-hs) : `stack install tldr` -- [Node.js client](https://github.com/tldr-pages/tldr-node-client) : `npm install -g tldr` -- [Perl5 client](https://github.com/shoichikaji/perl-tldr): `cpanm App::tldr` -- [PHP client](https://github.com/BrainMaestro/tldr-php): `composer global require brainmaestro/tldr` + - [tldr-man-page](https://github.com/freesuraj/TLDR), available on + [App Store](https://appsto.re/sg/IQ0-_.i) + - [tldr-pages](https://github.com/mflint/ios-tldr-viewer), available on + [App Store](https://itunes.apple.com/us/app/tldt-pages/id1071725095?ls=1&mt=8) +- [Haskell client](https://github.com/psibi/tldr-hs): + `stack install tldr` +- [Node.js client](https://github.com/tldr-pages/tldr-node-client): + `npm install -g tldr` +- [Perl5 client](https://github.com/shoichikaji/perl-tldr): + `cpanm App::tldr` +- [PHP client](https://github.com/BrainMaestro/tldr-php): + `composer global require brainmaestro/tldr` - Python clients: - - [tldr-python-client](https://github.com/tldr-pages/tldr-python-client) : `pip install tldr` - - [tldr.py](https://github.com/lord63/tldr.py): `pip install tldr.py` -- [R client](https://github.com/kirillseva/tldrrr): `devtools::install_github('kirillseva/tldrrr')` -- [Ruby client](https://github.com/YellowApple/tldrb): `gem install tldrb` + - [tldr-python-client](https://github.com/tldr-pages/tldr-python-client): + `pip install tldr` + - [tldr.py](https://github.com/lord63/tldr.py): + `pip install tldr.py` +- [R client](https://github.com/kirillseva/tldrrr): + `devtools::install_github('kirillseva/tldrrr')` +- [Ruby client](https://github.com/YellowApple/tldrb): + `gem install tldrb` - Rust clients: - - [rust-tldr](https://github.com/rilut/rust-tldr) (online lookup): `cargo install tldr` - - [tealdeer](https://github.com/dbrgn/tealdeer) (fully featured client with offline cache): `cargo install tealdeer` + - [rust-tldr](https://github.com/rilut/rust-tldr) + (thin client with online lookup): + `cargo install tldr` + - [tealdeer](https://github.com/dbrgn/tealdeer) + (fully featured client with offline cache): + `cargo install tealdeer` - Web clients: - [tldr.jsx](https://github.com/ostera/tldr.jsx): http://tldr.ostera.io/ - [DistroWatch](https://distrowatch.com/dwres.php?resource=man-pages) -There is also a comprehensive [list of clients in our Wiki](https://github.com/tldr-pages/tldr/wiki/TLDR-clients). +There is also a comprehensive +[list of clients in our Wiki](https://github.com/tldr-pages/tldr/wiki/TLDR-clients). ## Contributing @@ -97,22 +123,30 @@ There is also a comprehensive [list of clients in our Wiki](https://github.com/t - You can think of more examples for an existing command? Contributions are most welcome! -Have a look at the [contributing guidelines](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md) -and go ahead! +We strive to maintain a [welcoming and collaborative](GOVERNANCE.md) community. +Have a look at the [contributing guidelines](CONTRIBUTING.md), and go ahead! ## Similar projects -- [Cheat](https://github.com/chrisallenlane/cheat) allows you to create and view interactive cheatsheets on the command-line. - It was designed to help remind *nix system administrators of options for commands that they use frequently, but not frequently enough to remember. +- [Cheat](https://github.com/chrisallenlane/cheat) + allows you to create and view interactive cheatsheets on the command-line. + It was designed to help remind *nix system administrators of options + for commands that they use frequently, but not frequently enough to remember. -- [Bro pages](http://bropages.org/) are a highly readable supplement to man pages. +- [Bro pages](http://bropages.org/) + are a highly readable supplement to man pages. Bro pages show concise, common-case examples for Unix commands. - The examples are submitted by the user base, and can be voted up or down; the best entries are what people see first when they look up a command. - -- [eg](https://github.com/srsudar/eg) provides detailed examples with explanations on the command line. Examples come from the repository, but eg allows you to display custom examples and commands alongside the defaults. + The examples are submitted by the user base, and can be voted up or down; + the best entries are what people see first when they look up a command. + +- [eg](https://github.com/srsudar/eg) + provides detailed examples with explanations on the command line. + Examples come from the repository, but `eg` supports displaying + custom examples and commands alongside the defaults. ## What does "tldr" mean? TL;DR stands for "Too Long; Didn't Read". -It originates in Internet slang, where it is used to indicate parts of the text skipped as too lengthy. -Read more in the [TLDR article on Wikipedia](https://en.wikipedia.org/wiki/TL;DR). +It originates in Internet slang, where it is used to indicate that a long text +(or parts of it) has been skipped as too lengthy. +Read more in Wikipedia's [TL;DR article](https://en.wikipedia.org/wiki/TL;DR). diff --git a/contributing-guides/maintainers-guide.md b/contributing-guides/maintainers-guide.md new file mode 100644 index 000000000..838323336 --- /dev/null +++ b/contributing-guides/maintainers-guide.md @@ -0,0 +1,45 @@ +# Maintainer's guide + +The following guidelines are meant to provide a general basis +for the behavior expected of tldr-pages maintainers: + +- When responding to issues or pull requests, + remember that you're temporarily the face of the tldr-pages project. + **Be welcoming and friendly**, and if you don't know how to answer, + ping other maintainers who you think might have a say. + +- Although push access allows committing directly to the repository, + plase **create pull requests for all of your changes**, + except the simplest ones (e.g. typo fixes). + This ensures that the entire process other contributors go through + is exposed to maintainers, + who can then identify and address bottlenecks or inconveniences. + Similarly, **avoid merging your own PRs**. + +- **Every new discussion should receive a response within 3 days (ideally)**. + You can respond yourself + or ask other members to provide their thoughts/opinions. + +- When merging PRs, use the strategy that produces a **clean git history**: + Use squash if there's a single commit in the PR, + or if the multiple commits are not independent changes. + If the PR author took the time to craft individual, + informative commit messages for each commit, + use regular merge to honor that work and preserve the history of the changes. + +- **Know when and how to say no**. + Sometimes requests or contributions need to be declined, + at least in their current form. + The project has developed multiple guidelines over time to handle edge cases + — get acquainted with them, and point them out when necessary. + Be polite, but firm: it saves everyone's time and patience + to make expectations clear early. + +- Always remember to **thank every contribution**, + even when it can't be accepted (in fact, especially then). + Keep in mind that + [every form of contribution](https://github.com/kentcdodds/all-contributors) + (pull request, feature request, bug report, etc.) + is a voluntary gift of time offered to the tldr project + by someone who cares about it, + so make sure not to take it for granted. diff --git a/contributing-guides/project-governance.md b/contributing-guides/project-governance.md deleted file mode 100644 index c3b2f2e62..000000000 --- a/contributing-guides/project-governance.md +++ /dev/null @@ -1,8 +0,0 @@ -Romain Prieto (@rprieto) -Igor Shubovych (@igorshubovych) -Ruben Vereecken (@rubenvereecken) -Waldir Pimenta (@waldyrious) -Felix Yan (@felixonmars) -Leandro Ostera (@ostera) -Agniva De Sarker (@agnivade) -Starbeamrainbowlabs (@sbrl)