lilith/tldr
1
0
Fork 0
mirror of https://github.com/tldr-pages/tldr.git synced 2025-04-22 00:42:08 +02:00
Code Activity

Merge pull request #1839 from tldr-pages/governance

Browse source 
[RFC] Project governance, Maintainer's guide
This commit is contained in:
Starbeamrainbowlabs 2018-01-09 18:46:14 +00:00 • committed by GitHub
commit 7fac214286
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 258 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
CONTRIBUTING.md
View file

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

126
GOVERNANCE.md Normal file
View file

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

20
MAINTAINERS.md Normal file
View file

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

96
README.md
View file

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

45
contributing-guides/maintainers-guide.md Normal file
View file

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

8
contributing-guides/project-governance.md
View file

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