Skip to content

Latest commit

 

History

History
188 lines (138 loc) · 7.73 KB

CONTRIBUTE.md

File metadata and controls

188 lines (138 loc) · 7.73 KB
Raw

How to Contribute to PowerTOP

If you are interested in PowerTOP and wish to put some time and effort into it, this is the document for you. Filing bug reports, translating text strings, editing or creating documentation, helping fellow users, or making changes to the program source code are some of the ways you can contribute to the project.

Thank you for your interest in PowerTOP. We appreciate your effort, time, and continued participation in this project.

Official source code repository

The official source code repository is hosted on GitHub*, so a GitHub account is strongly recommended for effective collaboration. All bug filings, changes, and releases are hosted there:

Developers, check out the "Code Conventions" section further down. We look forward to your pull requests!

Finding bugs

No software is perfect. Since PowerTOP is a diagnostic/debug tool concerned with your system, different hardware may behave differently than we expect, resulting in weird behaviors (or crashes). There are plenty of bugs to be found and squashed, and we appreciate your willingness to help.

Bugs will be filed here:

It is important to note that bug filings are the start of a conversation, and conversations are two-way streets. When you find a bug, do not merely "file and forget". Expect follow-up questions to be asked. We may even ask you to patch, re-compile, and re-run to see if our change(s) fix your issue, especially if your system's particular behavior(s) have revealed the bug.

If one of us asks you to do something that tests the limits of your comfort or ability, say so, and we will do our best to help you.

Writing documentation

Here is the layout of PowerTOP's documentation:

  • CONTRIBUTE.md is this document
  • README.md covers cloning, building, and getting started with PowerTOP
  • doc/powertop.8 is the (roff) manual page for the project
  • Code comments (or lack thereof)

PowerTOP, at present, does not generate a library for use by other programs, so there is no "PowerTOP API". The source code does have internal functions and APIs for specific duties that are key to program functionality. Those need to be thoroughly documented for future developers.

Markdown documents follow the latest CommonMark spec. Generally speaking, do not use GitHub's proprietary extensions to Markdown syntax.

The manual page uses roff syntax.

Code comments are described in the "Code Conventions" section further down.

Localization

PowerTOP uses gettext for localization. Translating strings is done using PO files, and those are contributed back to PowerTOP through a GitHub pull request.

If you are new to gettext, here is the official documentation for it:

The gettext project also has some links to commonly-used PO editors:

Code conventions

PowerTOP's maintainers will enforce the Linux* kernel coding style.

That style guide is tailored for the Linux kernel, so "I" is Linus Torvalds. For the purposes of the PowerTOP project, the maintainers of PowerTOP have the final say on style. If a specific thing does not apply to PowerTOP, the essence of the guidance almost surely does. This section will be expanded upon as needed.

While C++ is used in some parts of the codebase, C-style comments are preferred. This is copy-pasted directly from the kernel style guide:

/*
 * This is the preferred style for multi-line
 * comments in the Linux kernel source code.
 * Please use it consistently.
 *
 * Description:  A column of asterisks on the left side,
 * with beginning and ending almost-blank lines.
 */

There are sections of that style guide that are specific to the kernel-- the "Allocating Memory" and "Don't re-invent the kernel macros" sections come to mind. The essential take-aways from those sections are: "Use the right function for the right job" and "do not re-invent existing functionality". That is sound development advice for any software project.

The PowerTOP code base is constantly evolving, and the code base has been around for a while. Expect to see code that does not follow the kernel style guide. If you find any such code, fix it or let us know. Those are style bugs that need fixing.

When you submit a patch to the PowerTOP project, we assume you agree to what's written in the "License" section below.

License

PowerTOP is a GPLv2 project (see COPYING and README.md). All contributions will be licensed under the terms of the GPLv2.

If you create a new source file or header, here is the comment to be placed at the beginning (from line 1) of the new file:

/*
 * Copyright (C) yyyy  name of author
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; version 2.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 *
 * SPDX-License-Identifier: GPL-2.0-only
 */

All contributions to PowerTOP must adhere to the Linux kernel's "Developer's Certificate of Origin", which we will copy-paste here for completeness:

By making a contribution to this project, you 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.

From: Developer's Cerificate of Origin

Thank You!

Again, thank you! Your time and effort are greatly appreciated! We look forward to your contributions, and appreciate your continued participation in the project!