Skip to content

Commit 79c4c03

Browse files
kaikreuzerkaikreuzer
committed
Added documentation about maintainers
Signed-off-by: Kai Kreuzer <[email protected]> (github: @kaikreuzer)
1 parent aed383a commit 79c4c03

10 files changed

+286
-5
lines changed

‎AUTHORS

+12-5
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,14 @@
11
# This file lists all individuals having contributed content to the repository.
2-
# If you're submitting a patch, please add your name here in alphabetical order as part of the patch.
3-
#
4-
# For a list of active project maintainers, see the MAINTAINERS file.
5-
#
2+
# For how it is generated, see `project-orga/generate-authors.sh`.
3+
4+
Dancho Penev <[email protected]>
5+
Gerhard Riegler <[email protected]>
6+
Gideon le Grange <[email protected]>
7+
Jochen Hiller <[email protected]>
68
Kai Kreuzer <[email protected]>
7-
Thomas Eichstädt-Engelen <[email protected]>
9+
kaikreuzer <[email protected]>
10+
Karel Goderis <[email protected]>
11+
kgoderis <[email protected]>
12+
manroh <[email protected]>
13+
Marcel Verpaalen <[email protected]>
14+
Oliver Libutzki <[email protected]>

‎CONTRIBUTING.md

+38
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,18 @@ name and email address match your git configuration. The AUTHORS file is
100100
regenerated occasionally from the git commit history, so a mismatch may result
101101
in your changes being overwritten.
102102

103+
### Merge approval
104+
105+
Docker maintainers use LGTM (Looks Good To Me) in comments on the code review
106+
to indicate acceptance.
107+
108+
A change requires LGTMs from an absolute majority of the maintainers of each
109+
component affected. For example, if a change affects `docs/` and `addons/`, it
110+
needs an absolute majority from the maintainers of `docs/` AND, separately, an
111+
absolute majority of the maintainers of `addons/`.
112+
113+
For more details see [MAINTAINERS.md](project-orga/MAINTAINERS.md)
114+
103115
### Sign your work
104116

105117
The sign-off is a simple line at the end of the explanation for the
@@ -177,3 +189,29 @@ There are several exceptions to the signing requirement. Currently these are:
177189

178190
Don't forget: being a maintainer is a time investment. Make sure you will have time to make yourself available.
179191
You don't have to be a maintainer to make a difference on the project!
192+
193+
## Community Guidelines
194+
195+
We want to keep the openHAB community awesome, growing and collaborative. We
196+
need your help to keep it that way. To help with this we've come up with some
197+
general guidelines for the community as a whole:
198+
199+
* Be nice: Be courteous, respectful and polite to fellow community members: no
200+
regional, racial, gender, or other abuse will be tolerated. We like nice people
201+
way better than mean ones!
202+
203+
* Encourage diversity and participation: Make everyone in our community
204+
feel welcome, regardless of their background and the extent of their
205+
contributions, and do everything possible to encourage participation in
206+
our community.
207+
208+
* Keep it legal: Basically, don't get us in trouble. Share only content that
209+
you own, do not share private or sensitive information, and don't break the
210+
law.
211+
212+
* Stay on topic: Make sure that you are posting to the correct channel
213+
and avoid off-topic discussions. Remember when you update an issue or
214+
respond to an email you are potentially sending to a large number of
215+
people. Please consider this before you update. Also remember that
216+
nobody likes spam.
217+

‎MAINTAINERS

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Kai Kreuzer <[email protected]> (@kaikreuzer)

‎project-orga/CONTRIBUTING.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../CONTRIBUTING.md

‎project-orga/MAINTAINERS

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Kai Kreuzer <[email protected]> (@kaikreuzer)

‎project-orga/MAINTAINERS.md

+148
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# The openHAB Maintainer manual
2+
3+
## Introduction
4+
5+
Dear maintainer. Thank you for investing the time and energy to help
6+
make openHAB as useful as possible. Maintaining a project is difficult,
7+
sometimes unrewarding work. Sure, you will get to contribute cool
8+
features to the project. But most of your time will be spent reviewing,
9+
cleaning up, documenting, answering questions, and justifying design
10+
decisions - while everyone has all the fun! But remember - the quality
11+
of the maintainers' work is what distinguishes the good projects from
12+
the great. So please be proud of your work, even the unglamourous parts,
13+
and encourage a culture of appreciation and respect for *every* aspect
14+
of improving the project - not just the hot new features.
15+
16+
This document is a manual for maintainers old and new. It explains what
17+
is expected of maintainers, how they should work, and what tools are
18+
available to them.
19+
20+
This is a living document - if you see something out of date or missing,
21+
speak up!
22+
23+
## What is a maintainer's responsibility?
24+
25+
It is every maintainer's responsibility to:
26+
27+
1. Expose a clear road map for improving their component.
28+
2. Deliver prompt feedback and decisions on pull requests.
29+
3. Be available to anyone with questions, bug reports, criticism etc.
30+
on their component. This includes GitHub requests and the mailing
31+
list.
32+
4. Make sure their component respects the philosophy, design and
33+
road map of the project.
34+
35+
## How are decisions made?
36+
37+
Short answer: with pull requests to the openHAB 2 repository.
38+
39+
openHAB is an open-source project with an open design philosophy. This
40+
means that the repository is the source of truth for EVERY aspect of the
41+
project, including its philosophy, design, road map, and APIs. *If it's
42+
part of the project, it's in the repo. If it's in the repo, it's part of
43+
the project.*
44+
45+
As a result, all decisions can be expressed as changes to the
46+
repository. An implementation change is a change to the source code. An
47+
API change is a change to the API specification. A philosophy change is
48+
a change to the philosophy manifesto, and so on.
49+
50+
All decisions affecting openHAB, big and small, follow the same 3 steps:
51+
52+
* Step 1: Open a pull request. Anyone can do this.
53+
54+
* Step 2: Discuss the pull request. Anyone can do this.
55+
56+
* Step 3: Accept (`LGTM`) or refuse a pull request. The relevant maintainers do
57+
this (see below "Who decides what?")
58+
+ Accepting pull requests
59+
- If the pull request appears to be ready to merge, give it a `LGTM`, which
60+
stands for "Looks Good To Me".
61+
- If the pull request has some small problems that need to be changed, make
62+
a comment adressing the issues.
63+
- If the changes needed to a PR are small, you can add a "LGTM once the
64+
following comments are adressed..." this will reduce needless back and
65+
forth.
66+
- If the PR only needs a few changes before being merged, any MAINTAINER can
67+
make a replacement PR that incorporates the existing commits and fixes the
68+
problems before a fast track merge.
69+
+ Closing pull requests
70+
- If a PR appears to be abandoned, after having attempted to contact the
71+
original contributor, then a replacement PR may be made. Once the
72+
replacement PR is made, any contributor may close the original one.
73+
- If you are not sure if the pull request implements a good feature or you
74+
do not understand the purpose of the PR, ask the contributor to provide
75+
more documentation. If the contributor is not able to adequately explain
76+
the purpose of the PR, the PR may be closed by any MAINTAINER.
77+
- If a MAINTAINER feels that the pull request is sufficiently architecturally
78+
flawed, or if the pull request needs significantly more design discussion
79+
before being considered, the MAINTAINER should close the pull request with
80+
a short explanation of what discussion still needs to be had. It is
81+
important not to leave such pull requests open, as this will waste both the
82+
MAINTAINER's time and the contributor's time. It is not good to string a
83+
contributor on for weeks or months, having them make many changes to a PR
84+
that will eventually be rejected.
85+
86+
## Who decides what?
87+
88+
All decisions are pull requests, and the relevant maintainers make
89+
decisions by accepting or refusing pull requests. Review and acceptance
90+
by anyone is denoted by adding a comment in the pull request: `LGTM`.
91+
However, only currently listed `MAINTAINERS` are counted towards the
92+
required majority.
93+
94+
openHAB follows the timeless, highly efficient and totally unfair system
95+
known as [Benevolent dictator for
96+
life](http://en.wikipedia.org/wiki/Benevolent_Dictator_for_Life), with
97+
yours truly, Kai Kreuzer, in the role of BDFL. This means that all
98+
decisions are made, by default, by Kai. Since making every decision
99+
myself would be highly un-scalable, in practice decisions are spread
100+
across multiple maintainers.
101+
102+
The relevant maintainers for a pull request can be worked out in 2 steps:
103+
104+
* Step 1: Determine the subdirectories affected by the pull request. This
105+
might be `addons/binding/org.openhab.binding.sonos`,
106+
`docs/source/installation`, or any other part of the repo.
107+
108+
* Step 2: Find the `MAINTAINERS` file which affects this directory. If the
109+
directory itself does not have a `MAINTAINERS` file, work your way up
110+
the repo hierarchy until you find one.
111+
112+
There is also a `project-prga/getmaintainers.sh` script that will print out the
113+
maintainers for a specified directory.
114+
115+
### I'm a maintainer, and I'm going on holiday
116+
117+
Please let your co-maintainers and other contributors know by raising a pull
118+
request that comments out your `MAINTAINERS` file entry using a `#`.
119+
120+
### I'm a maintainer. Should I make pull requests too?
121+
122+
Yes. Nobody should ever push to master directly. All changes should be
123+
made through a pull request.
124+
125+
### Helping contributors with the DCO
126+
127+
The [DCO or `Sign your work`](
128+
https://github.com/openhab/openhab2/blob/master/CONTRIBUTING.md#sign-your-work)
129+
requirement is not intended as a roadblock or speed bump.
130+
131+
Some openHAB contributors are not as familiar with `git`, or have used a web based
132+
editor, and thus asking them to `git commit --amend -s` is not the best way forward.
133+
134+
In this case, maintainers can update the commits based on clause (c) of the DCO. The
135+
most trivial way for a contributor to allow the maintainer to do this, is to add
136+
a DCO signature in a Pull Requests's comment, or a maintainer can simply note that
137+
the change is sufficiently trivial that it does not substantivly change the existing
138+
contribution - i.e., a spelling change.
139+
140+
When you add someone's DCO, please also add your own to keep a log.
141+
142+
### Who assigns maintainers?
143+
144+
Kai has final `LGTM` approval for all pull requests to `MAINTAINERS` files.
145+
146+
### How is this process changed?
147+
148+
Just like everything else: by making a pull request :)

‎project-orga/NOTICE

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
The content of this folder has been heavily influenced (not to say 'copied')
2+
from the Docker project (https://github.com/docker/docker),
3+
which publishes the content under the Apache License, Version 2.0.
4+
5+
Big kudos therefore go to Docker for the great process and tools!

‎project-orga/allmaintainers.sh

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#!/bin/sh
2+
3+
find $1 -name MAINTAINERS -exec cat {} ';' | sed -E -e 's/^[^:]*: *(.*)$/\1/' | grep -E -v -e '^ *$' -e '^ *#.*$' | sort -u

‎project-orga/generate-authors.sh

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#!/bin/bash
2+
set -e
3+
4+
cd "$(dirname "$(readlink "$BASH_SOURCE")")/.."
5+
6+
# see also ".mailmap" for how email addresses and names are deduplicated
7+
8+
{
9+
cat <<-'EOH'
10+
# This file lists all individuals having contributed content to the repository.
11+
# For how it is generated, see `project-orga/generate-authors.sh`.
12+
EOH
13+
echo
14+
git log --format='%aN <%aE>' | sort -uf
15+
} > AUTHORS

‎project-orga/getmaintainer.sh

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
#!/usr/bin/env bash
2+
set -e
3+
4+
if [ $# -ne 1 ]; then
5+
echo >&2 "Usage: $0 PATH"
6+
echo >&2 "Show the primary and secondary maintainers for a given path"
7+
exit 1
8+
fi
9+
10+
set -e
11+
12+
DEST=$1
13+
DESTFILE=""
14+
if [ ! -d $DEST ]; then
15+
DESTFILE=$(basename $DEST)
16+
DEST=$(dirname $DEST)
17+
fi
18+
19+
MAINTAINERS=()
20+
cd $DEST
21+
while true; do
22+
if [ -e ./MAINTAINERS ]; then
23+
{
24+
while read line; do
25+
re='^([^:]*): *(.*)$'
26+
file=$(echo $line | sed -E -n "s/$re/\1/p")
27+
if [ ! -z "$file" ]; then
28+
if [ "$file" = "$DESTFILE" ]; then
29+
echo "Override: $line"
30+
maintainer=$(echo $line | sed -E -n "s/$re/\2/p")
31+
MAINTAINERS=("$maintainer" "${MAINTAINERS[@]}")
32+
fi
33+
else
34+
MAINTAINERS+=("$line");
35+
fi
36+
done;
37+
} < MAINTAINERS
38+
break
39+
fi
40+
if [ -d .git ]; then
41+
break
42+
fi
43+
if [ "$(pwd)" = "/" ]; then
44+
break
45+
fi
46+
cd ..
47+
done
48+
49+
PRIMARY="${MAINTAINERS[0]}"
50+
PRIMARY_FIRSTNAME=$(echo $PRIMARY | cut -d' ' -f1)
51+
LGTM_COUNT=${#MAINTAINERS[@]}
52+
LGTM_COUNT=$((LGTM_COUNT%2 +1))
53+
54+
firstname() {
55+
echo $1 | cut -d' ' -f1
56+
}
57+
58+
echo "A pull request in $1 will need $LGTM_COUNT LGTM's to be merged."
59+
echo "--- $PRIMARY is the PRIMARY MAINTAINER of $1."
60+
for SECONDARY in "${MAINTAINERS[@]:1}"; do
61+
echo "--- $SECONDARY"
62+
done

0 commit comments

Comments
 (0)