mirror of
https://github.com/danieldemus/openhab-core.git
synced 2025-01-25 11:45:49 +01:00
updated contribution info
Signed-off-by: Kai Kreuzer <kai@openhab.org>
This commit is contained in:
Kai Kreuzer
parent
2b810a75c8
commit
098bc56db1
@ -1,18 +1,14 @@
|
||||
# Contributing to openHAB
|
||||
# Contributing to openHAB Core components
|
||||
|
||||
Want to hack on openHAB? Awesome! Here are instructions to get you
|
||||
started. They are probably not perfect, please let us know if anything
|
||||
feels wrong or incomplete.
|
||||
Warning: Note that this is most likely not the project you are looking for.
|
||||
|
||||
## Reporting Issues
|
||||
openHAB mainly consist out of the core components from Eclipse SmartHome (https://github.com/eclipse/smarthome),
|
||||
extensions that are openHAB1-compatible from https://github.com/openhab/openhab and extensions that are
|
||||
openHAB2-compatible from https://github.com/openhab/openhab2. All is then packaged into a distribution in
|
||||
https://github.com/openhab/openhab-distro.
|
||||
|
||||
Please report [openHAB2 specific issues here](https://github.com/openhab/openhab2/issues), while issues that are related to the core framework should be reported in the [bugzilla of Eclipse SmartHome](https://bugs.eclipse.org/bugs/buglist.cgi?product=SmartHome&component=Core).
|
||||
Do not worry, if you are not clear, which category your issue belongs to - we will redirect you, if necessary.
|
||||
|
||||
## Build Environment
|
||||
|
||||
For instructions on setting up your development environment, please
|
||||
see our dedicated [IDE setup guide](https://github.com/openhab/openhab/wiki/IDE-Setup).
|
||||
This project here only contains a few bundles of the core runtime that are openHAB specific and thus not contained
|
||||
in the Eclipse SmartHome project.
|
||||
|
||||
## Contribution guidelines
|
||||
|
||||
@ -33,25 +29,12 @@ that feature *on top of* openHAB.
|
||||
|
||||
### Discuss your design on the mailing list
|
||||
|
||||
We recommend discussing your plans [in the discussion forum](https://community.openhab.org/c/openhab-2)
|
||||
We recommend discussing your plans [in the discussion forum](https://community.openhab.org/)
|
||||
before starting to code - especially for more ambitious contributions.
|
||||
This gives other contributors a chance to point you in the right
|
||||
direction, give feedback on your design, and maybe point out if someone
|
||||
else is working on the same thing.
|
||||
|
||||
### Create issues...
|
||||
|
||||
Any significant improvement should be documented as [a GitHub
|
||||
issue](https://github.com/openhab/openhab2/issues?labels=enhancement&page=1&state=open) before anybody
|
||||
starts working on it.
|
||||
|
||||
### ...but check for existing issues first!
|
||||
|
||||
Please take a moment to check that an issue doesn't already exist
|
||||
documenting your bug report or improvement proposal. If it does, it
|
||||
never hurts to add a quick "+1" or "I have this problem too". This will
|
||||
help prioritize the most common problems and requests.
|
||||
|
||||
### Conventions
|
||||
|
||||
Fork the repo and make changes on your fork in a feature branch:
|
||||
@ -100,18 +83,6 @@ name and email address match your git configuration. The AUTHORS file is
|
||||
regenerated occasionally from the git commit history, so a mismatch may result
|
||||
in your changes being overwritten.
|
||||
|
||||
### Merge approval
|
||||
|
||||
openHAB maintainers use LGTM (Looks Good To Me) in comments on the code review
|
||||
to indicate acceptance.
|
||||
|
||||
A change requires LGTMs from an absolute majority of the maintainers of each
|
||||
component affected. For example, if a change affects `docs/` and `addons/`, it
|
||||
needs an absolute majority from the maintainers of `docs/` AND, separately, an
|
||||
absolute majority of the maintainers of `addons/`.
|
||||
|
||||
For more details see [MAINTAINERS.md](project-orga/MAINTAINERS.md)
|
||||
|
||||
### Sign your work
|
||||
|
||||
The sign-off is a simple line at the end of the explanation for the
|
||||
@ -165,15 +136,6 @@ then you just add a line to every git commit message:
|
||||
|
||||
using your real name (sorry, no pseudonyms or anonymous contributions.)
|
||||
|
||||
One way to automate this, is customise your get ``commit.template`` by adding
|
||||
a ``prepare-commit-msg`` hook to your openHAB checkout:
|
||||
|
||||
```
|
||||
curl -L -o .git/hooks/prepare-commit-msg https://raw.github.com/openhab/openhab2/master/contrib/prepare-commit-msg.hook && chmod +x .git/hooks/prepare-commit-msg
|
||||
```
|
||||
|
||||
* Note: the above script expects to find your GitHub user name in ``git config --get github.user``
|
||||
|
||||
#### Small patch exception
|
||||
|
||||
There are several exceptions to the signing requirement. Currently these are:
|
||||
@ -181,15 +143,6 @@ There are several exceptions to the signing requirement. Currently these are:
|
||||
* Your patch fixes spelling or grammar errors.
|
||||
* Your patch is a single line change to documentation.
|
||||
|
||||
### How can I become a maintainer?
|
||||
|
||||
* Step 1: learn the component inside out
|
||||
* Step 2: make yourself useful by contributing code, bugfixes, support etc.
|
||||
* Step 3: volunteer on [the discussion group] (https://github.com/openhab/openhab2/issues?labels=question&page=1&state=open)
|
||||
|
||||
Don't forget: being a maintainer is a time investment. Make sure you will have time to make yourself available.
|
||||
You don't have to be a maintainer to make a difference on the project!
|
||||
|
||||
## Community Guidelines
|
||||
|
||||
We want to keep the openHAB community awesome, growing and collaborative. We
|
||||
|
||||
@ -1 +0,0 @@
|
||||
../CONTRIBUTING.md
|
||||
@ -1 +0,0 @@
|
||||
Kai Kreuzer <kai@openhab.org> (@kaikreuzer)
|
||||
@ -1,148 +0,0 @@
|
||||
# The openHAB Maintainer manual
|
||||
|
||||
## Introduction
|
||||
|
||||
Dear maintainer. Thank you for investing the time and energy to help
|
||||
make openHAB as useful as possible. Maintaining a project is difficult,
|
||||
sometimes unrewarding work. Sure, you will get to contribute cool
|
||||
features to the project. But most of your time will be spent reviewing,
|
||||
cleaning up, documenting, answering questions, and justifying design
|
||||
decisions - while everyone has all the fun! But remember - the quality
|
||||
of the maintainers' work is what distinguishes the good projects from
|
||||
the great. So please be proud of your work, even the unglamourous parts,
|
||||
and encourage a culture of appreciation and respect for *every* aspect
|
||||
of improving the project - not just the hot new features.
|
||||
|
||||
This document is a manual for maintainers old and new. It explains what
|
||||
is expected of maintainers, how they should work, and what tools are
|
||||
available to them.
|
||||
|
||||
This is a living document - if you see something out of date or missing,
|
||||
speak up!
|
||||
|
||||
## What is a maintainer's responsibility?
|
||||
|
||||
It is every maintainer's responsibility to:
|
||||
|
||||
1. Expose a clear road map for improving their component.
|
||||
2. Deliver prompt feedback and decisions on pull requests.
|
||||
3. Be available to anyone with questions, bug reports, criticism etc.
|
||||
on their component. This includes GitHub requests and the mailing
|
||||
list.
|
||||
4. Make sure their component respects the philosophy, design and
|
||||
road map of the project.
|
||||
|
||||
## How are decisions made?
|
||||
|
||||
Short answer: with pull requests to the openHAB 2 repository.
|
||||
|
||||
openHAB is an open-source project with an open design philosophy. This
|
||||
means that the repository is the source of truth for EVERY aspect of the
|
||||
project, including its philosophy, design, road map, and APIs. *If it's
|
||||
part of the project, it's in the repo. If it's in the repo, it's part of
|
||||
the project.*
|
||||
|
||||
As a result, all decisions can be expressed as changes to the
|
||||
repository. An implementation change is a change to the source code. An
|
||||
API change is a change to the API specification. A philosophy change is
|
||||
a change to the philosophy manifesto, and so on.
|
||||
|
||||
All decisions affecting openHAB, big and small, follow the same 3 steps:
|
||||
|
||||
* Step 1: Open a pull request. Anyone can do this.
|
||||
|
||||
* Step 2: Discuss the pull request. Anyone can do this.
|
||||
|
||||
* Step 3: Accept (`LGTM`) or refuse a pull request. The relevant maintainers do
|
||||
this (see below "Who decides what?")
|
||||
+ Accepting pull requests
|
||||
- If the pull request appears to be ready to merge, give it a `LGTM`, which
|
||||
stands for "Looks Good To Me".
|
||||
- If the pull request has some small problems that need to be changed, make
|
||||
a comment adressing the issues.
|
||||
- If the changes needed to a PR are small, you can add a "LGTM once the
|
||||
following comments are adressed..." this will reduce needless back and
|
||||
forth.
|
||||
- If the PR only needs a few changes before being merged, any MAINTAINER can
|
||||
make a replacement PR that incorporates the existing commits and fixes the
|
||||
problems before a fast track merge.
|
||||
+ Closing pull requests
|
||||
- If a PR appears to be abandoned, after having attempted to contact the
|
||||
original contributor, then a replacement PR may be made. Once the
|
||||
replacement PR is made, any contributor may close the original one.
|
||||
- If you are not sure if the pull request implements a good feature or you
|
||||
do not understand the purpose of the PR, ask the contributor to provide
|
||||
more documentation. If the contributor is not able to adequately explain
|
||||
the purpose of the PR, the PR may be closed by any MAINTAINER.
|
||||
- If a MAINTAINER feels that the pull request is sufficiently architecturally
|
||||
flawed, or if the pull request needs significantly more design discussion
|
||||
before being considered, the MAINTAINER should close the pull request with
|
||||
a short explanation of what discussion still needs to be had. It is
|
||||
important not to leave such pull requests open, as this will waste both the
|
||||
MAINTAINER's time and the contributor's time. It is not good to string a
|
||||
contributor on for weeks or months, having them make many changes to a PR
|
||||
that will eventually be rejected.
|
||||
|
||||
## Who decides what?
|
||||
|
||||
All decisions are pull requests, and the relevant maintainers make
|
||||
decisions by accepting or refusing pull requests. Review and acceptance
|
||||
by anyone is denoted by adding a comment in the pull request: `LGTM`.
|
||||
However, only currently listed `MAINTAINERS` are counted towards the
|
||||
required majority.
|
||||
|
||||
openHAB follows the timeless, highly efficient and totally unfair system
|
||||
known as [Benevolent dictator for
|
||||
life](http://en.wikipedia.org/wiki/Benevolent_Dictator_for_Life), with
|
||||
yours truly, Kai Kreuzer, in the role of BDFL. This means that all
|
||||
decisions are made, by default, by Kai. Since making every decision
|
||||
myself would be highly un-scalable, in practice decisions are spread
|
||||
across multiple maintainers.
|
||||
|
||||
The relevant maintainers for a pull request can be worked out in 2 steps:
|
||||
|
||||
* Step 1: Determine the subdirectories affected by the pull request. This
|
||||
might be `addons/binding/org.openhab.binding.sonos`,
|
||||
`docs/source/installation`, or any other part of the repo.
|
||||
|
||||
* Step 2: Find the `MAINTAINERS` file which affects this directory. If the
|
||||
directory itself does not have a `MAINTAINERS` file, work your way up
|
||||
the repo hierarchy until you find one.
|
||||
|
||||
There is also a `project-prga/getmaintainers.sh` script that will print out the
|
||||
maintainers for a specified directory.
|
||||
|
||||
### I'm a maintainer, and I'm going on holiday
|
||||
|
||||
Please let your co-maintainers and other contributors know by raising a pull
|
||||
request that comments out your `MAINTAINERS` file entry using a `#`.
|
||||
|
||||
### I'm a maintainer. Should I make pull requests too?
|
||||
|
||||
Yes. Nobody should ever push to master directly. All changes should be
|
||||
made through a pull request.
|
||||
|
||||
### Helping contributors with the DCO
|
||||
|
||||
The [DCO or `Sign your work`](
|
||||
https://github.com/openhab/openhab2/blob/master/CONTRIBUTING.md#sign-your-work)
|
||||
requirement is not intended as a roadblock or speed bump.
|
||||
|
||||
Some openHAB contributors are not as familiar with `git`, or have used a web based
|
||||
editor, and thus asking them to `git commit --amend -s` is not the best way forward.
|
||||
|
||||
In this case, maintainers can update the commits based on clause (c) of the DCO. The
|
||||
most trivial way for a contributor to allow the maintainer to do this, is to add
|
||||
a DCO signature in a Pull Requests's comment, or a maintainer can simply note that
|
||||
the change is sufficiently trivial that it does not substantivly change the existing
|
||||
contribution - i.e., a spelling change.
|
||||
|
||||
When you add someone's DCO, please also add your own to keep a log.
|
||||
|
||||
### Who assigns maintainers?
|
||||
|
||||
Kai has final `LGTM` approval for all pull requests to `MAINTAINERS` files.
|
||||
|
||||
### How is this process changed?
|
||||
|
||||
Just like everything else: by making a pull request :)
|
||||
@ -1,5 +0,0 @@
|
||||
The content of this folder has been heavily influenced (not to say 'copied')
|
||||
from the Docker project (https://github.com/docker/docker),
|
||||
which publishes the content under the Apache License, Version 2.0.
|
||||
|
||||
Big kudos therefore go to Docker for the great process and tools!
|
||||
@ -1,3 +0,0 @@
|
||||
#!/bin/sh
|
||||
|
||||
find $1 -name MAINTAINERS -exec cat {} ';' | sed -E -e 's/^[^:]*: *(.*)$/\1/' | grep -E -v -e '^ *$' -e '^ *#.*$' | sort -u
|
||||
@ -1,15 +0,0 @@
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
cd "$(dirname "$(readlink "$BASH_SOURCE")")/.."
|
||||
|
||||
# see also ".mailmap" for how email addresses and names are deduplicated
|
||||
|
||||
{
|
||||
cat <<-'EOH'
|
||||
# This file lists all individuals having contributed content to the repository.
|
||||
# For how it is generated, see `project-orga/generate-authors.sh`.
|
||||
EOH
|
||||
echo
|
||||
git log --format='%aN <%aE>' | sort -uf
|
||||
} > AUTHORS
|
||||
@ -1,62 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -e
|
||||
|
||||
if [ $# -ne 1 ]; then
|
||||
echo >&2 "Usage: $0 PATH"
|
||||
echo >&2 "Show the primary and secondary maintainers for a given path"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
set -e
|
||||
|
||||
DEST=$1
|
||||
DESTFILE=""
|
||||
if [ ! -d $DEST ]; then
|
||||
DESTFILE=$(basename $DEST)
|
||||
DEST=$(dirname $DEST)
|
||||
fi
|
||||
|
||||
MAINTAINERS=()
|
||||
cd $DEST
|
||||
while true; do
|
||||
if [ -e ./MAINTAINERS ]; then
|
||||
{
|
||||
while read line; do
|
||||
re='^([^:]*): *(.*)$'
|
||||
file=$(echo $line | sed -E -n "s/$re/\1/p")
|
||||
if [ ! -z "$file" ]; then
|
||||
if [ "$file" = "$DESTFILE" ]; then
|
||||
echo "Override: $line"
|
||||
maintainer=$(echo $line | sed -E -n "s/$re/\2/p")
|
||||
MAINTAINERS=("$maintainer" "${MAINTAINERS[@]}")
|
||||
fi
|
||||
else
|
||||
MAINTAINERS+=("$line");
|
||||
fi
|
||||
done;
|
||||
} < MAINTAINERS
|
||||
break
|
||||
fi
|
||||
if [ -d .git ]; then
|
||||
break
|
||||
fi
|
||||
if [ "$(pwd)" = "/" ]; then
|
||||
break
|
||||
fi
|
||||
cd ..
|
||||
done
|
||||
|
||||
PRIMARY="${MAINTAINERS[0]}"
|
||||
PRIMARY_FIRSTNAME=$(echo $PRIMARY | cut -d' ' -f1)
|
||||
LGTM_COUNT=${#MAINTAINERS[@]}
|
||||
LGTM_COUNT=$((LGTM_COUNT%2 +1))
|
||||
|
||||
firstname() {
|
||||
echo $1 | cut -d' ' -f1
|
||||
}
|
||||
|
||||
echo "A pull request in $1 will need $LGTM_COUNT LGTM's to be merged."
|
||||
echo "--- $PRIMARY is the PRIMARY MAINTAINER of $1."
|
||||
for SECONDARY in "${MAINTAINERS[@]:1}"; do
|
||||
echo "--- $SECONDARY"
|
||||
done
|
||||
Loading…
Reference in New Issue
Block a user