From dc3ba33b4694f32128fa303dc1cc9cc013a25823 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Wed, 27 Dec 2017 00:45:57 +0000 Subject: [PATCH 01/13] move contributing-guides/project-governance.md -> MAINTAINERS.md --- contributing-guides/project-governance.md => MAINTAINERS.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename contributing-guides/project-governance.md => MAINTAINERS.md (100%) diff --git a/contributing-guides/project-governance.md b/MAINTAINERS.md similarity index 100% rename from contributing-guides/project-governance.md rename to MAINTAINERS.md From 7ff508fe36bad5f4bde2e152a851af436ba43ef1 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Wed, 27 Dec 2017 00:47:21 +0000 Subject: [PATCH 02/13] add a governance policy and expand MAINTAINERS.md --- GOVERNANCE.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++ MAINTAINERS.md | 28 ++++++++++----- 2 files changed, 115 insertions(+), 8 deletions(-) create mode 100644 GOVERNANCE.md diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 000000000..a6e76e557 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,95 @@ +# 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, 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](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md) + to get started. + +- All members of the community are expected to **be cordial in all communications**. + 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 messages may be exchanged, + e.g. when setting up services that require passwords, + but otherwise all exchanges that impact the project either happen in issue or 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 can voice their thoughts, + and different positions are ideally resolved via + [informed consent](https://en.wikipedia.org/wiki/Sociocracy#Consent_vs._consensus) + of the involved people, who accept the collective decision + as "good enough for now, safe enough to try". + + +## II. Role transitions + +The main goal of these principles is to support a continuous replenishing of the management team +via a **smooth transition flow between community roles** — +from newcomer, to occasional contributor, to regular contributor, to maintainer. +This way the project can adapt in a flexible way +to the the natural variations in availability and interest of its contributors, +ensuring long-term resilience, +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 instead 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 processes are transparent, predictable, and free from subective judgment, +the metrics used are simple, objective, and publicly available. + +- Regular contributors shall be recognized as collaborators in the organization. + + - Specifically: once a contributor has had **5 pull requests merged**, + they should be invited to become a + [**member of the tldr-pages organization**](https://github.com/orgs/tldr-pages/people). + 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. + +- Members of the organization who demonstrate interest in performing maintainership tasks, + by reviewing and/or merging PRs, responding to and labeling issues, and generally doing project maintenance work, + shall be made part of the maintenance team, and their name added to the list of current maintainers + in the [MAINTAINERS.md](MAINTAINERS.md) file. + + - Specifically: once a contributor has been an organization member for at least 3 months, + and has **reviewed or merged 10 pull requests** by other contributors, + they should be invited to become an **owner 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. + +- If a collaborator or maintainer stops being active in the project for more than 6 months, + their membership status will be equally deactivated, + and their name added to the list of former maintainers in the MAINTAINERS.md file. + Again, this is and merely a reflection of their actual involvement with the project, + not a demotion or punishment. In fact, if they return to active participation in the project, + they should be re-added back to the organization, to reflect that fact. + + - This inactivity threshold additionally ensures + that the list of organization members doesn't grow to unwieldy sizes, + and that it accurately reflects the active team managing the project. diff --git a/MAINTAINERS.md b/MAINTAINERS.md index c3b2f2e62..a6e10e08c 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,8 +1,20 @@ -Romain Prieto (@rprieto) -Igor Shubovych (@igorshubovych) -Ruben Vereecken (@rubenvereecken) -Waldir Pimenta (@waldyrious) -Felix Yan (@felixonmars) -Leandro Ostera (@ostera) -Agniva De Sarker (@agnivade) -Starbeamrainbowlabs (@sbrl) +## 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. From 4d970ea3197d899291d1791abcec48ba18e95704 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Wed, 27 Dec 2017 00:47:36 +0000 Subject: [PATCH 03/13] add a maintainer's guide --- contributing-guides/maintainers-guide.md | 37 ++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 contributing-guides/maintainers-guide.md diff --git a/contributing-guides/maintainers-guide.md b/contributing-guides/maintainers-guide.md new file mode 100644 index 000000000..ffa8293f4 --- /dev/null +++ b/contributing-guides/maintainers-guide.md @@ -0,0 +1,37 @@ +# 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 master, + 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**. + +- Ideally, **every new discussion should receive a response within 24 hours**. + You can respond yourself or ask other members to provide their thoughts/opinions. + +- When mergin PRs, use the strategy that produces a **clean git history** in the repository: + 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. From 6843ce969a0312b28b259a47d4cd18825979b470 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Wed, 27 Dec 2017 12:58:13 +0000 Subject: [PATCH 04/13] governance/maintainership guides: minor textual fixes --- GOVERNANCE.md | 7 ++++--- contributing-guides/maintainers-guide.md | 4 ++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index a6e76e557..431667f09 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -29,9 +29,10 @@ with no central authority. - **All communications are public**. There are no permanent private channels where maintainers discuss "internal" matters. - Occasional private chat messages may be exchanged, + Occasional private chat or email messages may be exchanged, e.g. when setting up services that require passwords, - but otherwise all exchanges that impact the project either happen in issue or PR discussions, + 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). @@ -88,7 +89,7 @@ the metrics used are simple, objective, and publicly available. and their name added to the list of former maintainers in the MAINTAINERS.md file. Again, this is and merely a reflection of their actual involvement with the project, not a demotion or punishment. In fact, if they return to active participation in the project, - they should be re-added back to the organization, to reflect that fact. + they should be added back to the organization, to reflect that fact. - This inactivity threshold additionally ensures that the list of organization members doesn't grow to unwieldy sizes, diff --git a/contributing-guides/maintainers-guide.md b/contributing-guides/maintainers-guide.md index ffa8293f4..aed2e5c9c 100644 --- a/contributing-guides/maintainers-guide.md +++ b/contributing-guides/maintainers-guide.md @@ -8,7 +8,7 @@ for the behavior expected of tldr-pages maintainers: **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 master, +- 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 @@ -18,7 +18,7 @@ for the behavior expected of tldr-pages maintainers: - Ideally, **every new discussion should receive a response within 24 hours**. You can respond yourself or ask other members to provide their thoughts/opinions. -- When mergin PRs, use the strategy that produces a **clean git history** in the repository: +- When merging PRs, use the strategy that produces a **clean git history** in the repository: 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. From 29025a48a3561f34d2f26a0ff456c3eef92b14f3 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Wed, 27 Dec 2017 23:33:55 +0000 Subject: [PATCH 05/13] link to GOVERNANCE.md from README.md and CONTRIBUTING.md --- CONTRIBUTING.md | 3 ++- README.md | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) 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/README.md b/README.md index 7ba021114..6bcedfe56 100644 --- a/README.md +++ b/README.md @@ -97,8 +97,8 @@ 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 From 0a9f6f02d43a41d39171701a42f78edf6957017d Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 9 Jan 2018 09:51:41 +0000 Subject: [PATCH 06/13] wrap README to 80 characters (where possible) --- README.md | 92 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 63 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 6bcedfe56..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 @@ -102,17 +128,25 @@ 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). From 652590372d9f573d30b6e1715df46fd25c6d99aa Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 9 Jan 2018 09:54:19 +0000 Subject: [PATCH 07/13] maintainers-guide.md: wrap to 80 characters --- contributing-guides/maintainers-guide.md | 26 ++++++++++++++++-------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/contributing-guides/maintainers-guide.md b/contributing-guides/maintainers-guide.md index aed2e5c9c..fcfb6090c 100644 --- a/contributing-guides/maintainers-guide.md +++ b/contributing-guides/maintainers-guide.md @@ -12,26 +12,34 @@ for the behavior expected of tldr-pages maintainers: 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. + is exposed to maintainers, + who can then identify and address bottlenecks or inconveniences. Similarly, **avoid merging your own PRs**. - Ideally, **every new discussion should receive a response within 24 hours**. - You can respond yourself or ask other members to provide their thoughts/opinions. + 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** in the repository: - 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, +- 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. + 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. + 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) + 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, + 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. From 33fc4653c97ae71b40074670a236ceb3aac9891f Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 9 Jan 2018 10:23:56 +0000 Subject: [PATCH 08/13] GOVERNANCE.md: wrap to 80 characters --- GOVERNANCE.md | 68 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 44 insertions(+), 24 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 431667f09..b416a36e4 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -15,20 +15,25 @@ with no central authority. - **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](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md) + 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 members of the community are expected to **be cordial in all communications**. - Avoid making assumptions about the others' intentions, and make your own intentions clear. +- All members of the community are expected to + **be cordial in all communications**. + 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. + 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 @@ -39,7 +44,8 @@ with no central authority. - **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 can voice their thoughts, + What it means is that + every interested member of the community can voice their thoughts, and different positions are ideally resolved via [informed consent](https://en.wikipedia.org/wiki/Sociocracy#Consent_vs._consensus) of the involved people, who accept the collective decision @@ -48,20 +54,23 @@ with no central authority. ## II. Role transitions -The main goal of these principles is to support a continuous replenishing of the management team +The main goal of these principles +is to support a continuous replenishing of the management team via a **smooth transition flow between community roles** — from newcomer, to occasional contributor, to regular contributor, to maintainer. This way the project can adapt in a flexible way to the the natural variations in availability and interest of its contributors, -ensuring long-term resilience, -and avoiding [single points of failure](https://en.wikipedia.org/wiki/Bus_factor). +ensuring long-term resilience, 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 instead 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, +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 processes are transparent, predictable, and free from subective judgment, +To ensure that these processes are +transparent, predictable, and free from subective judgment, the metrics used are simple, objective, and publicly available. - Regular contributors shall be recognized as collaborators in the organization. @@ -69,26 +78,37 @@ the metrics used are simple, objective, and publicly available. - Specifically: once a contributor has had **5 pull requests merged**, they should be invited to become a [**member of the tldr-pages organization**](https://github.com/orgs/tldr-pages/people). - This means they will be able to push commits to all of the organization's repositories, + 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. + Note: All members of the tldr-pages organization + must make their membership public. -- Members of the organization who demonstrate interest in performing maintainership tasks, - by reviewing and/or merging PRs, responding to and labeling issues, and generally doing project maintenance work, - shall be made part of the maintenance team, and their name added to the list of current maintainers +- Members of the organization + who demonstrate interest in performing maintainership tasks, + by reviewing and/or merging PRs, responding to and labeling issues, + and generally doing project maintenance work, + shall be made part of the maintenance team, + and their name added to the list of current maintainers in the [MAINTAINERS.md](MAINTAINERS.md) file. - - Specifically: once a contributor has been an organization member for at least 3 months, + - Specifically: once a contributor has been an organization member + for at least 3 months, and has **reviewed or merged 10 pull requests** by other contributors, - they should be invited to become an **owner of the tldr-pages organization**. + they should be invited to become + an **owner 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. -- If a collaborator or maintainer stops being active in the project for more than 6 months, - their membership status will be equally deactivated, - and their name added to the list of former maintainers in the MAINTAINERS.md file. - Again, this is and merely a reflection of their actual involvement with the project, - not a demotion or punishment. In fact, if they return to active participation in the project, +- If a collaborator or maintainer stops being active in the project + for more than 6 months, + their membership status will be equally deactivated + and their name added to the list of former maintainers + in the MAINTAINERS.md file. + Again, this is and merely a reflection + of their actual involvement with the project, + not a demotion or punishment. + In fact, if they return to active participation in the project, they should be added back to the organization, to reflect that fact. - This inactivity threshold additionally ensures From bbda579072762e62f0370d0c43437e9228306950 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 9 Jan 2018 10:37:29 +0000 Subject: [PATCH 09/13] GOVERNANCE.md: make some passages clearer and more neutral --- GOVERNANCE.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index b416a36e4..7880e0d5e 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -7,7 +7,7 @@ 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, improve and adapt them as needed, +the entire community can read, apply, improve and adapt them as needed, with no central authority. @@ -22,8 +22,7 @@ with no central authority. Please take a look at [CONTRIBUTING.md](CONTRIBUTING.md) to get started. -- All members of the community are expected to - **be cordial in all communications**. +- **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. @@ -41,7 +40,7 @@ with no central authority. 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.** +- **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 @@ -55,7 +54,7 @@ with no central authority. ## II. Role transitions The main goal of these principles -is to support a continuous replenishing of the management team +is to encourage a continuous replenishing of the management team via a **smooth transition flow between community roles** — from newcomer, to occasional contributor, to regular contributor, to maintainer. This way the project can adapt in a flexible way @@ -69,9 +68,9 @@ 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 processes are -transparent, predictable, and free from subective judgment, -the metrics used are simple, objective, and publicly available. +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. - Regular contributors shall be recognized as collaborators in the organization. @@ -102,13 +101,13 @@ the metrics used are simple, objective, and publicly available. - If a collaborator or maintainer stops being active in the project for more than 6 months, - their membership status will be equally deactivated + their membership status should be equally ceased and their name added to the list of former maintainers in the MAINTAINERS.md file. Again, this is and merely a reflection of their actual involvement with the project, not a demotion or punishment. - In fact, if they return to active participation in the project, + Indeed, if they return to active participation in the project, they should be added back to the organization, to reflect that fact. - This inactivity threshold additionally ensures From c181a4a7c4d810d102eee486bab137f420ca25d1 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 9 Jan 2018 10:39:33 +0000 Subject: [PATCH 10/13] GOVERNANCE.md: role-transitioning guidelines are not exhaustive --- GOVERNANCE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 7880e0d5e..a8280534b 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -71,6 +71,8 @@ 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 shall be recognized as collaborators in the organization. From b66bcccb107ade7c02186f7700825349b27eaac1 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 9 Jan 2018 10:42:47 +0000 Subject: [PATCH 11/13] maintainers-guide.md: make responsiveness recommendation sound less deadline-y --- contributing-guides/maintainers-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing-guides/maintainers-guide.md b/contributing-guides/maintainers-guide.md index fcfb6090c..838323336 100644 --- a/contributing-guides/maintainers-guide.md +++ b/contributing-guides/maintainers-guide.md @@ -16,7 +16,7 @@ for the behavior expected of tldr-pages maintainers: who can then identify and address bottlenecks or inconveniences. Similarly, **avoid merging your own PRs**. -- Ideally, **every new discussion should receive a response within 24 hours**. +- **Every new discussion should receive a response within 3 days (ideally)**. You can respond yourself or ask other members to provide their thoughts/opinions. From fde2d6a808547aac0e1f94cba863e2780f2dd53a Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 9 Jan 2018 14:20:16 +0000 Subject: [PATCH 12/13] GOVERNANCE.md: clarify guideline about collective decision-making --- GOVERNANCE.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index a8280534b..9acc5dc60 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -44,11 +44,11 @@ with no central authority. 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 can voice their thoughts, - and different positions are ideally resolved via - [informed consent](https://en.wikipedia.org/wiki/Sociocracy#Consent_vs._consensus) - of the involved people, who accept the collective decision - as "good enough for now, safe enough to try". + 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 From 1d8975b3c706aca4f30cb6799a7f2bcf6636452e Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 9 Jan 2018 14:21:34 +0000 Subject: [PATCH 13/13] GOVERNANCE.md: rework role transitions section to define 3 stages --- GOVERNANCE.md | 85 ++++++++++++++++++++++++++++----------------------- 1 file changed, 47 insertions(+), 38 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 9acc5dc60..fa1f5874f 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -53,17 +53,16 @@ with no central authority. ## II. Role transitions -The main goal of these principles -is to encourage a continuous replenishing of the management team -via a **smooth transition flow between community roles** — +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 can adapt in a flexible way -to the the natural variations in availability and interest of its contributors, -ensuring long-term resilience, and avoiding +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 instead aim to **recognize the work that people already do**. +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. @@ -74,44 +73,54 @@ 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 shall be recognized as collaborators in the organization. +- **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. - - Specifically: once a contributor has had **5 pull requests merged**, - they should be invited to become a - [**member of the tldr-pages organization**](https://github.com/orgs/tldr-pages/people). - 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. +- **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. -- Members of the organization - who demonstrate interest in performing maintainership tasks, - by reviewing and/or merging PRs, responding to and labeling issues, - and generally doing project maintenance work, - shall be made part of the maintenance team, - and their name added to the list of current maintainers +- **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. - - Specifically: once a contributor has been an organization member - for at least 3 months, - and has **reviewed or merged 10 pull requests** by other contributors, - they should be invited to become - an **owner 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. - -- If a collaborator or maintainer stops being active in the project - for more than 6 months, - their membership status should be equally ceased +- **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. - - - This inactivity threshold additionally ensures - that the list of organization members doesn't grow to unwieldy sizes, - and that it accurately reflects the active team managing the project.