openbmc/docs/CONTRIBUTING.md

11 [Code of Conduct](https://github.com/openbmc/docs/blob/master/code-of-conduct.md).
20 <https://www.opencompute.org/documents/ocp-terminology-guidelines-for-inclusion-and-openness>
25 limited set of responsibilities. These communicate over D-Bus with other
29 daemon, which then translates those requests to D-Bus messages.
43 - [Individual CLA](https://drive.google.com/file/d/1k3fc7JPgzKdItEfyIoLxMCVbPUhTwooY)
44 - [Corporate CLA](https://drive.google.com/file/d/1d-2M8ng_Dl2j1odsvZ8o1QHAdHB-pNSH)
65 you are interested in a particular repository - for example, "bmcweb" - type
68 review comment.
81 <https://www.python.org/dev/peps/pep-0008/>
96 max-line-length = 80
115 [Example .clang-format](https://www.github.com/openbmc/docs/blob/master/style/javascript/.clang-for…
126 …nel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst>
130 - Indent with tabs instead of spaces, set at 8 columns
132 - 80-column lines
134 - Opening braces on the end of a line, except for functions
139 astyle --style=linux --indent=tab=8 --indent=force-tab=8
144 See [C++ Style and Conventions](./cpp-style-and-conventions.md).
158 [design_template](https://github.com/openbmc/docs/blob/master/designs/design-template.md).
164 Linux kernel) might need to be sent as patches or a git pull request.
171 - Too large: "convert foo to new API; also fix CVE 1234 in bar"
172 - Too small: "move abc.h to top of include list" and "move xyz.h to bottom of
174 - Just right: "convert foo to new API" and "convert foo from tab to space"
178 - If your change has a specification, sketch out your ideas first and work to
180 - Work at most a few days before seeking review.
181 - Commit and review header files before writing code.
182 - Commit and review each implementation module separately.
187 possible, your commit should stand alone on top of master - "Fix whitespace in
200 When someone makes a comment on your commit in Gerrit, modify that commit and
201 send it again to Gerrit. This typically involves `git rebase --interactive` or
202 `git commit --amend`, for which there are many guides online. As mentioned in
209 should be clearly written - even more so than production code, unit tests are
210 meant primarily to be read by humans - and should test both good and bad
212 [testing documentation](https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md)
216 whitespace changes - this makes review unnecessarily difficult.
222 - Concisely, _what_ change are you making? e.g. "libpldm: Add APIs to enable
224 - Comprehensively, _why_ are you making that change? In some cases, like a small
227 - Concisely, _how_ did you test? (see below).
248 All commit messages must include a "Signed-off-by" line, which indicates that
279 - <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>
280 - <https://www.kernel.org/doc/html/latest/process/submit-checklist.html>
296 found under Projects -> List:
312 phosphor-state-manager, and 'openbmc.gerrit' is the name of the Host previously
326 [Change-Ids](https://gerrit-review.googlesource.com/Documentation/user-changeid.html)
328 repository to automatically add a Change-Id to your commit messages. The steps
332 gitdir=$(git rev-parse --git-dir)
333 curl https://gerrit.openbmc.org/tools/hooks/commit-msg -o ${gitdir}/hooks/commit-msg
334 chmod +x ${gitdir}/hooks/commit-msg
343 spans across few projects) or (un)mark the change as Work-in-Progress. For that
345 [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/intro-user.html#topics).
360 or abandoned. When you re-work your change, remember to use `git commit --amend`
369 ## References to non-public resources
376 no dependencies on non-public resources (URLs, repositories, etc).
378 ## Best practices for D-Bus interfaces
380 - New D-Bus interfaces should be reusable
382 - Type signatures should and use the simplest types possible, appropriate for
385 - D-Bus interfaces are defined in the `phosphor-dbus-interfaces` repository at:
387 <https://github.com/openbmc/phosphor-dbus-interfaces>
389 See: <http://dbus.freedesktop.org/doc/dbus-api-design.html>
396 - Do not use `system(<some shell pipeline>)`. Reading and writing from files
402 - Use the `stdint` types (eg, `uint32_t`, `int8_t`) for data that needs to be a
405 - Don't assume that `char` is signed or unsigned.
407 - Beware of endian considerations when reading to & writing from C types
409 - Declare internal-only functions as `static`, declare read-only data as `const`
412 - Ensure that your code compiles without warnings, especially for changes to the
417 - Systemd services should be contained within the OpenBMC repository they are
420 - Systemd services should list their dependencies using Wants/After to ensure
423 - If your repository provides a shared library, it should appropriately handle
424   any D-Bus dependencies it has
427   or it may be ensuring the required D-Bus service is automatically activated
430 - See this
431   [doc](https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md)
440 partial-time capacity, may be in a timezone far from your own, and may have very
447 Discord - but a reasonable timeframe to do so is on the order of a week, not on
451 to maintain as possible. Part of the nature of open source is attrition -
452 contributors can come and go easily - so maintainers tend not to put stock in
482         personal information I submit with it, including my sign-off) is
493 following the [recommendation][lf-copyright] from the Linux Foundation with
499 // SPDX-License-Identifier: Apache-2.0
500 // SPDX-FileCopyrightText: Copyright OpenBMC Authors
506 authority to remove! This exception does not apply to previously non-public code
511 …ttps://github.com/spdx/spdx-spec/blob/support/2.3.1/chapters/file-tags.md#annex-h-specifying-spdx-…
512 [lf-copyright]:
513   https://www.linuxfoundation.org/blog/blog/copyright-notices-in-open-source-software-projects