Update contributing article
Signed-off-by: Thomas Dietrich <Thomas.Dietrich@tu-ilmenau.de>pull/154/head
Thomas Dietrich
Kai Kreuzer
parent
36c190a826
commit
fb709d0aa9
|
|
@ -7,9 +7,16 @@ title: Contributing to openHAB
|
||||||
|
|
||||||
# Contributing to openHAB
|
# Contributing to openHAB
|
||||||
|
|
||||||
|
openHAB is a community effort and everyone can take part in that.
|
||||||
|
Be it by being an active developer, a one time bug reporter or by commenting on issues by others.
|
||||||
|
Please the following guidelines.
|
||||||
|
|
||||||
## Reporting Issues
|
## Reporting Issues
|
||||||
|
|
||||||
Use the table below to determine where your issue or idea for improvement should be reported:
|
Before reporting an issue, please check the [openHAB community forum](https://community.openhab.org) for solutions and help.
|
||||||
|
More people will see your issue when it is posted in the forum and community members may be able to help you find known solutions/workarounds.
|
||||||
|
|
||||||
|
When no solution was found, use the table below to determine where your issue should be reported:
|
||||||
|
|
||||||
Issue | Where to report
|
Issue | Where to report
|
||||||
------|----------------
|
------|----------------
|
||||||
|
|
@ -21,11 +28,14 @@ Issues related to Eclipse SmartHome add-ons and core runtime | [Eclipse SmartHom
|
||||||
|
|
||||||
But do not worry - if you are not clear, which category your issue belongs to - we will redirect you, if necessary.
|
But do not worry - if you are not clear, which category your issue belongs to - we will redirect you, if necessary.
|
||||||
|
|
||||||
|
Please pay attention to the respective `CONTRIBUTING.md` file in all of these repositories.
|
||||||
|
They include further details on how to report an issue or file a pull request.
|
||||||
|
|
||||||
## 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.
|
||||||
need your help to keep it that way. To help with this we've come up with some
|
We need your help to keep it that way.
|
||||||
general guidelines for the community as a whole:
|
To help with this we've come up with some general guidelines for the community as a whole:
|
||||||
|
|
||||||
* **Be nice:** Be courteous, respectful and polite to fellow community members: no
|
* **Be nice:** Be courteous, respectful and polite to fellow community members: no
|
||||||
regional, racial, gender, or other abuse will be tolerated. We like nice people
|
regional, racial, gender, or other abuse will be tolerated. We like nice people
|
||||||
|
|
|
||||||
|
|
@ -1,212 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: documentation
|
layout: redirected
|
||||||
title: Contribution
|
sitemap: false
|
||||||
|
redirect_to: /appendix/contributing.html
|
||||||
---
|
---
|
||||||
|
|
||||||
# Contributing to openHAB
|
<!-- Note to authors: This file was created in December 2016. Feel free to remove it after a few months... -->
|
||||||
|
|
||||||
Before reporting an issue, please check the [openHAB forum] (https://community.openhab.org) for solutions and help. More people will see your issue when it is posted in the forum and community members may be able to help you find known solutions/workarounds for your issue.
|
|
||||||
|
|
||||||
When no solution was found, use the table below to determine where your issue should be logged:
|
|
||||||
|
|
||||||
Issue | Where to report
|
|
||||||
------|----------------
|
|
||||||
Problems and feature requests for openHAB 1 addons | [openHAB](https://github.com/openhab/openhab/issues)
|
|
||||||
Problems and feature requests for openHAB 2 addons | [openHAB2](https://github.com/openhab/openhab2/issues)
|
|
||||||
Issues related to the runtime environment, IDE and packaging | [openHAB-distro](https://github.com/openhab/openhab-distro/issues)
|
|
||||||
Issues related to the core openHAB bundles that are not from Eclipse SmartHome | [openHAB-core](https://github.com/kaikreuzer/openhab-core/issues)
|
|
||||||
Issues related to Eclipse SmartHome addons and core runtime | [Eclipse SmartHome](https://github.com/eclipse/smarthome/issues)
|
|
||||||
|
|
||||||
But do not worry - if you are not clear, which category your issue belongs to - we will redirect you, if necessary.
|
|
||||||
|
|
||||||
## Contribution guidelines
|
|
||||||
|
|
||||||
### Pull requests are always welcome
|
|
||||||
|
|
||||||
We are always thrilled to receive pull requests, and do our best to
|
|
||||||
process them as fast as possible. Not sure if that typo is worth a pull
|
|
||||||
request? Do it! We will appreciate it.
|
|
||||||
|
|
||||||
If your pull request is not accepted on the first try, don't be
|
|
||||||
discouraged! If there's a problem with the implementation, hopefully you
|
|
||||||
received feedback on what to improve.
|
|
||||||
|
|
||||||
We're trying very hard to keep openHAB lean and focused. We don't want it
|
|
||||||
to do everything for everybody. This means that we might decide against
|
|
||||||
incorporating a new feature. However, there might be a way to implement
|
|
||||||
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/)
|
|
||||||
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/openhab-distro/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:
|
|
||||||
|
|
||||||
- If it's a bugfix branch, name it XXX-something where XXX is the number of the
|
|
||||||
issue
|
|
||||||
- If it's a feature branch, create an enhancement issue to announce your
|
|
||||||
intentions, and name it XXX-something where XXX is the number of the issue.
|
|
||||||
|
|
||||||
Submit unit tests for your changes. openHAB has a great test framework built in; use
|
|
||||||
it! Take a look at existing tests for inspiration. Run the full test suite on
|
|
||||||
your branch before submitting a pull request.
|
|
||||||
|
|
||||||
Update the documentation when creating or modifying features. Test
|
|
||||||
your documentation changes for clarity, concision, and correctness, as
|
|
||||||
well as a clean documentation build.
|
|
||||||
|
|
||||||
Write clean code. Universally formatted code promotes ease of writing, reading,
|
|
||||||
and maintenance.
|
|
||||||
|
|
||||||
Pull requests descriptions should be as clear as possible and include a
|
|
||||||
reference to all the issues that they address.
|
|
||||||
|
|
||||||
Pull requests must not contain commits from other users or branches.
|
|
||||||
|
|
||||||
Commit messages must start with a capitalized and short summary (max. 50
|
|
||||||
chars) written in the imperative, followed by an optional, more detailed
|
|
||||||
explanatory text which is separated from the summary by an empty line.
|
|
||||||
|
|
||||||
Code review comments may be added to your pull request. Discuss, then make the
|
|
||||||
suggested modifications and push additional commits to your feature branch. Be
|
|
||||||
sure to post a comment after pushing. The new commits will show up in the pull
|
|
||||||
request automatically, but the reviewers will not be notified unless you
|
|
||||||
comment.
|
|
||||||
|
|
||||||
Before the pull request is merged, make sure that you squash your commits into
|
|
||||||
logical units of work using `git rebase -i` and `git push -f`. After every
|
|
||||||
commit the test suite should be passing. Include documentation changes in the
|
|
||||||
same commit so that a revert would remove all traces of the feature or fix.
|
|
||||||
|
|
||||||
Commits that fix or close an issue should include a reference like `Closes #XXX`
|
|
||||||
or `Fixes #XXX`, which will automatically close the issue when merged.
|
|
||||||
|
|
||||||
Add your name to the AUTHORS file, but make sure the list is sorted and your
|
|
||||||
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 `distributions/`, 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
|
|
||||||
patch, which certifies that you wrote it or otherwise have the right to
|
|
||||||
pass it on as an open-source patch. The rules are pretty simple: if you
|
|
||||||
can certify the below (from
|
|
||||||
[developercertificate.org](http://developercertificate.org/)):
|
|
||||||
|
|
||||||
```
|
|
||||||
Developer Certificate of Origin
|
|
||||||
Version 1.1
|
|
||||||
|
|
||||||
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
|
|
||||||
660 York Street, Suite 102,
|
|
||||||
San Francisco, CA 94110 USA
|
|
||||||
|
|
||||||
Everyone is permitted to copy and distribute verbatim copies of this
|
|
||||||
license document, but changing it is not allowed.
|
|
||||||
|
|
||||||
|
|
||||||
Developer's Certificate of Origin 1.1
|
|
||||||
|
|
||||||
By making a contribution to this project, I certify that:
|
|
||||||
|
|
||||||
(a) The contribution was created in whole or in part by me and I
|
|
||||||
have the right to submit it under the open source license
|
|
||||||
indicated in the file; or
|
|
||||||
|
|
||||||
(b) The contribution is based upon previous work that, to the best
|
|
||||||
of my knowledge, is covered under an appropriate open source
|
|
||||||
license and I have the right under that license to submit that
|
|
||||||
work with modifications, whether created in whole or in part
|
|
||||||
by me, under the same open source license (unless I am
|
|
||||||
permitted to submit under a different license), as indicated
|
|
||||||
in the file; or
|
|
||||||
|
|
||||||
(c) The contribution was provided directly to me by some other
|
|
||||||
person who certified (a), (b) or (c) and I have not modified
|
|
||||||
it.
|
|
||||||
|
|
||||||
(d) I understand and agree that this project and the contribution
|
|
||||||
are public and that a record of the contribution (including all
|
|
||||||
personal information I submit with it, including my sign-off) is
|
|
||||||
maintained indefinitely and may be redistributed consistent with
|
|
||||||
this project or the open source license(s) involved.
|
|
||||||
```
|
|
||||||
|
|
||||||
then you just add a line to every git commit message:
|
|
||||||
|
|
||||||
Signed-off-by: Joe Smith <joe.smith@email.com> (github: github_handle)
|
|
||||||
|
|
||||||
using your real name (sorry, no pseudonyms or anonymous contributions.)
|
|
||||||
|
|
||||||
#### Small patch exception
|
|
||||||
|
|
||||||
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 [in the community] (https://community.openhab.org/)
|
|
||||||
|
|
||||||
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
|
|
||||||
need your help to keep it that way. To help with this we've come up with some
|
|
||||||
general guidelines for the community as a whole:
|
|
||||||
|
|
||||||
* Be nice: Be courteous, respectful and polite to fellow community members: no
|
|
||||||
regional, racial, gender, or other abuse will be tolerated. We like nice people
|
|
||||||
way better than mean ones!
|
|
||||||
|
|
||||||
* Encourage diversity and participation: Make everyone in our community
|
|
||||||
feel welcome, regardless of their background and the extent of their
|
|
||||||
contributions, and do everything possible to encourage participation in
|
|
||||||
our community.
|
|
||||||
|
|
||||||
* Keep it legal: Basically, don't get us in trouble. Share only content that
|
|
||||||
you own, do not share private or sensitive information, and don't break the
|
|
||||||
law.
|
|
||||||
|
|
||||||
* Stay on topic: Make sure that you are posting to the correct channel
|
|
||||||
and avoid off-topic discussions. Remember when you update an issue or
|
|
||||||
respond to an email you are potentially sending to a large number of
|
|
||||||
people. Please consider this before you update. Also remember that
|
|
||||||
nobody likes spam.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue