demus/openhab-core
1
0
Fork 0
mirror of https://github.com/danieldemus/openhab-core.git synced 2025-02-04 08:03:53 +01:00
Code Issues 1 Packages Projects Releases Wiki Activity

updated contribution info

Browse Source 
Signed-off-by: Kai Kreuzer <kai@openhab.org>
This commit is contained in:
Kai Kreuzer 2015-12-30 23:44:04 +01:00
parent 2b810a75c8
commit 098bc56db1
8 changed files with 9 additions and 291 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
CONTRIBUTING.md
View File

@ -1,18 +1,14 @@
# Contributing to openHAB # Contributing to openHAB Core components
Want to hack on openHAB? Awesome! Here are instructions to get you Warning: Note that this is most likely not the project you are looking for.
started. They are probably not perfect, please let us know if anything
feels wrong or incomplete.
## 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). This project here only contains a few bundles of the core runtime that are openHAB specific and thus not contained
Do not worry, if you are not clear, which category your issue belongs to - we will redirect you, if necessary. in the Eclipse SmartHome project.
## 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).
## Contribution guidelines ## Contribution guidelines
@ -33,25 +29,12 @@ that feature *on top of* openHAB.
### Discuss your design on the mailing list ### 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. before starting to code - especially for more ambitious contributions.
This gives other contributors a chance to point you in the right This gives other contributors a chance to point you in the right
direction, give feedback on your design, and maybe point out if someone direction, give feedback on your design, and maybe point out if someone
else is working on the same thing. 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 ### Conventions
Fork the repo and make changes on your fork in a feature branch: 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 regenerated occasionally from the git commit history, so a mismatch may result
in your changes being overwritten. 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 ### Sign your work
The sign-off is a simple line at the end of the explanation for the 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.) 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 #### Small patch exception
There are several exceptions to the signing requirement. Currently these are: 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 fixes spelling or grammar errors.
* Your patch is a single line change to documentation. * 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 ## Community Guidelines
We want to keep the openHAB community awesome, growing and collaborative. We We want to keep the openHAB community awesome, growing and collaborative. We

1
project-orga/CONTRIBUTING.md
View File

@ -1 +0,0 @@
../CONTRIBUTING.md

1
project-orga/MAINTAINERS
View File

@ -1 +0,0 @@
Kai Kreuzer <kai@openhab.org> (@kaikreuzer)

148
project-orga/MAINTAINERS.md
View File

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

5
project-orga/NOTICE
View File

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

3
project-orga/allmaintainers.sh
View File

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

15
project-orga/generate-authors.sh
View File

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

62
project-orga/getmaintainer.sh
View File

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