Merge pull request #1839 from tldr-pages/governance

[RFC] Project governance, Maintainer's guide

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).

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.

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 `<romain.prieto@gmail.com>` (@rprieto)
+- Igor Shubovych `<igor.shubovych@gmail.com>` (@igorshubovych)
+- Ruben Vereecken `<rubenvereecken@gmail.com>` (@rubenvereecken)
+- Waldir Pimenta `<waldyrious@gmail.com>` (@waldyrious)
+- Felix Yan `<felixonmars@archlinux.org>` (@felixonmars)
+- Leandro Ostera `<leandro@ostera.io>` (@ostera)
+- Agniva De Sarker `<agnivade@yahoo.co.in>` (@agnivade)
+- Starbeamrainbowlabs `<feedback@starbeamrainbowlabs.com>` (@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.

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`
+- [C++ client](https://github.com/tldr-pages/tldr-cpp-client):
-- [Crystal client](https://github.com/porras/tlcr): `brew install porras/tap/tlcr`
+  `brew install tldr`
-- [Dart client](https://github.com/hterkelsen/tldr): `pub global activate tldr`
+- [Crystal client](https://github.com/porras/tlcr):
-- [Elixir client](https://github.com/edgurgel/tldr_elixir_client) (binaries not yet available)
+  `brew install porras/tap/tlcr`
-- [Emacs client](https://github.com/kuanyui/tldr.el), available on [MELPA](https://github.com/melpa/melpa)
+- [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))
+  - [github.com/pranavraja/tldr](https://github.com/pranavraja/tldr):
-  - [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))
+    `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-man-page](https://github.com/freesuraj/TLDR), available on
-  - [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)
+    [App Store](https://appsto.re/sg/IQ0-_.i)
-- [Haskell client](https://github.com/psibi/tldr-hs) : `stack install tldr`
+  - [tldr-pages](https://github.com/mflint/ios-tldr-viewer), available on
-- [Node.js client](https://github.com/tldr-pages/tldr-node-client) : `npm install -g tldr`
+    [App Store](https://itunes.apple.com/us/app/tldt-pages/id1071725095?ls=1&mt=8)
-- [Perl5 client](https://github.com/shoichikaji/perl-tldr): `cpanm App::tldr`
+- [Haskell client](https://github.com/psibi/tldr-hs):
-- [PHP client](https://github.com/BrainMaestro/tldr-php): `composer global require brainmaestro/tldr`
+  `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-python-client](https://github.com/tldr-pages/tldr-python-client):
-  - [tldr.py](https://github.com/lord63/tldr.py): `pip install tldr.py`
+    `pip install tldr`
-- [R client](https://github.com/kirillseva/tldrrr): `devtools::install_github('kirillseva/tldrrr')`
+  - [tldr.py](https://github.com/lord63/tldr.py):
-- [Ruby client](https://github.com/YellowApple/tldrb): `gem install tldrb`
+    `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`
+    - [rust-tldr](https://github.com/rilut/rust-tldr)
-    - [tealdeer](https://github.com/dbrgn/tealdeer) (fully featured client with offline cache): `cargo install tealdeer`
+      (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)
+We strive to maintain a [welcoming and collaborative](GOVERNANCE.md) community.
-and go ahead!
+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.
+- [Cheat](https://github.com/chrisallenlane/cheat)
-  It was designed to help remind *nix system administrators of options for commands that they use frequently, but not frequently enough to remember.
+  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.
+  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.
+
+- [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.
+It originates in Internet slang, where it is used to indicate that a long text
-Read more in the [TLDR article on Wikipedia](https://en.wikipedia.org/wiki/TL;DR).
+(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).

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.

contributing-guides/project-governance.md

@@ -1,8 +0,0 @@
-Romain Prieto <romain.prieto@gmail.com> (@rprieto)
-Igor Shubovych <igor.shubovych@gmail.com> (@igorshubovych)
-Ruben Vereecken <rubenvereecken@gmail.com> (@rubenvereecken)
-Waldir Pimenta <waldyrious@gmail.com> (@waldyrious)
-Felix Yan <felixonmars@archlinux.org> (@felixonmars)
-Leandro Ostera <leandro@ostera.io> (@ostera)
-Agniva De Sarker <agnivade@yahoo.co.in> (@agnivade)
-Starbeamrainbowlabs <feedback@starbeamrainbowlabs.com> (@sbrl)