|
| 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 :) |
0 commit comments