Skip to contentSkip to conversation

Rewrite README, and contribution guide

PATCH In review Joe Konno 2 participants 7 messages May 4, 2020 – May 7, 2020

lore
Share & tools
lore

Joe Konno

author
#0 lore raw

cover Rewrite README, and contribution guide

From: Joe Konno <joe.konno(a)intel.com>

This series rewrites the README using markdown syntax and adds a contribution guide.

Series was submitted as a GitHub pull request as well:
* https://github.com/fenrus75/powertop/pull/43

Thanks to my colleague, Doug Martin, for reviewing these changes.

CONTRIBUTE.md changes up development workflows in (hopefully) a good way. In my opinion, these are the key take-aways from that document:
* Use GitHub workflows for sharing/collaborating (e.g. PRs, Issues)
* Use the Linux kernel coding style

The README and CONTRIBUTE documents will continue to evolve, but this should get us going in the right direction.

PS: PowerTOP's project description on GitHub ("please post patches to the mailing list instead of using github pull requests") will be changed after this series is merged-- if it is.

Joe Konno (3):
README.md: rename, add md syntax, and major tweaks README.md: Fix a misspelled name
Add CONTRIBUTE.md

 CONTRIBUTE.md | 188 ++++++++++++++++++++++++++++++++++++++++++++++
 README        | 157 --------------------------------------
 README.md     | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 392 insertions(+), 157 deletions(-)
 create mode 100644 CONTRIBUTE.md
 delete mode 100644 README
 create mode 100644 README.md
Signature · 1 line
2.26.2
author
#1 lore raw

PATCH 1/3 README.md: rename, add md syntax, and major tweaks

From: Joe Konno <joe.konno(a)intel.com>

Make the README file a markdown document and rename accordingly. Add markdown syntax where needed. Rewrite the clunkiest bits, and add additional documentation where appropriate.

While in the file, made the project name (PowerTOP) consistent. Also removed some trailing spaces, hard-wrapped lines to 80 characters, and a few other low-hanging changes that made sense with markdown.

Note that a "Copyright and License" section was added. No changes to existing terms, but that section is needed for completeness.

Reviewed-by Doug Martin <doug.martin(a)intel.com>
Signed-off-by Joe Konno <joe.konno(a)intel.com>
---
 README    | 157 -----------------------------------------
 README.md | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 204 insertions(+), 157 deletions(-)
 delete mode 100644 README
 create mode 100644 README.md
README deleted +0 -157
deleted file mode 100644
index a2c32ca79d9e..000000000000
@@ -1,157 +0,0 @@
-Build dependencies
-------------------
-PowerTOP uses C++, and expects g++ and libstdc++ to be functional
-along with a glibc/pthreadsi, autoconf, automake, and libtool in the
-development environment.
-
-In addition to that, PowerTOP requires the following components:
-
-pciutils-devel (is only required if you have PCI)
-ncurses-devel  (required)
-libnl-devel    (required)
-kernel version => 2.6.38
-
-Example packages to install in Ubuntu:
-
-sudo apt install libpci-dev libnl-3-dev libnl-genl-3-dev gettext \
-libgettextpo-dev autopoint gettext libncurses5-dev libncursesw5-dev libtool-bin \
-dh-autoreconf autoconf-archive pkg-config
-
-Building & Installing PowerTOP
-------------------------------
-
-The autogen script is required to run only once to generate the configure for
-the build. Rest of the steps are required to run everytime there is a change
-made to the PowerTop.
-
-To build and install PowerTOP type the following commands,
-       ./autogen.sh
-       ./configure
-       make
-       sudo make install
-
-Note: For Android (running Intel Architecture ) there is a Android.mk
-that was provided by community members, and at this time is supported
-mostly by community members.
-
-Build PowerTop for Android LollyPop
-------------------------------------
-
-1. Obtain pciutils and ncurses libraries.
-   Skip this step if they are already in the tree.
-
-   pciutils: Clone
-       https://github.com/trevd/android_external_pciutils
-   into external/pciutils
-
-   ncurses: Clone
-       https://github.com/cvpcs/android_external_libncurses
-   into external/ncurses
-
-2. Run
-       ./src/csstoh.sh src/powertop.css src/css.h
-   to generate the css.h header file.
-
-3. Apply patches inside patches/Android
-
-4. PowerTop can be built with top level make,
-   or by doing "mm".
-
-   The resulting binary is under $ANDROID_PRODUCT_OUT/system/bin/powertop
-
-
-Kernel Parameters:
-------------------
-
-PowerTOP needs some kernel config options enabled in order function properly.
-As of linux-3.3.0 these are (list probably incomplete):
-
-CONFIG_NO_HZ
-CONFIG_HIGH_RES_TIMERS
-CONFIG_HPET_TIMER
-CONFIG_CPU_FREQ_GOV_ONDEMAND
-CONFIG_USB_SUSPEND
-CONFIG_SND_AC97_POWER_SAVE
-CONFIG_TIMER_STATS
-CONFIG_PERF_EVENTS
-CONFIG_PERF_COUNTERS
-CONFIG_TRACEPOINTS
-CONFIG_TRACING
-CONFIG_EVENT_POWER_TRACING_DEPRECATED
-CONFIG_X86_MSR
-ACPI_PROCFS_POWER
-CONFIG_DEBUG_FS
-
-Use these configs from linux-3.13.rc1
-CONFIG_POWERCAP
-CONFIG_INTEL_RAPL
-
-The patches in the patches/ sub-directory are required for PowerTOP to function
-fully.
-
-
-
-Outputting a report
--------------------
-When invoking PowerTOP without arguments, PowerTOP starts in interactive mode.
-However, for reporting bugs etc there is a special reporting modes:
-
-For an HTML formatted report simply execute PowerTOP with the following,  
-
-powertop --html
-
-which will create a "powertop.html" file which is static and can be sent to
-others to help diagnose power issues. Additionally has the feature of showing 
-the tunables executions within the report as a reference. 
-
-Note for the developers: If you make changes on the report format please
-make sure that the output can be cleanly validated by the W3C Markup
-Validation Service and W3C CSS Validation Service:
- * http://validator.w3.org/#validate_by_upload
- * http://jigsaw.w3.org/css-validator/#validate_by_upload
-
-For a CSV formatted report, simply execute PowerTOP with the following, 
-
-Powertop --csv 
-
-which will create a “powertop.csv” file which is static and can be used in 
-reporting, diagnoses, and analytical data analysis. 
-
-Also you can set the number of iterations, and duration of test, in which case 
-all reports will time stamp for you. 
-
-Calibrating & Power Numbers
----------------------------
-PowerTOP will, when running on battery, track your power consumption as well
-as your activity on the system. Once there are sufficient such measurements,
-PowerTOP can start to report power estimates for various activities.
-You can help get this estimation more accurate by running a calibration
-cycle:
-
-powertop --calibrate
-
-at least once; this will cycle through various display brightness levels
-(including "off") as well as USB device activities and some other workloads.
-
-
-Code from other open source projects
-------------------------------------
-PowerTOP contains some code from other open source projects; we'd like to
-thank the authors of those projects for their work. 
-Specifically PowerTOP contains code from
-
-Parse Event Library - Copyright 2009, 2010 Red Hat Inc  Steven Rosted <srostedt(a)redhat.com>
-nl80211 userspace tool - Copyright 2007, 2008	Johannes Berg <johannes(a)sipsolutions.net>
-
-
-Extech Power Analyzer / Datalogger support
-------------------------------------------
-I use, and our analysis teams use, the Extech Power Analyzer/Datalogger
-(model number 380803) quite a lot, and PowerTOP supports using this
-device over the serial cable. Just pass the device node on the command line
-like this
-
-powertop --extech=/dev/ttyUSB0
-
-(where ttyUSB0 is the devicenode of the serial-to-usb adapter on my system)
-
README.md new file +204 -0

204 lines not on this page · raw message

Signature · 1 line
2.26.2
#2 lore raw

[Powertop] Re: [PATCH 1/3 v1] README.md: rename, add md syntax, and major tweaks

Quoted 245 lines

-----Original Message-----
From: Joe Konno <joe.konno(a)linux.intel.com>
Sent: Monday, May 4, 2020 9:50 AM
To: powertop(a)lists.01.org
Subject: [Powertop] [PATCH 1/3 v1] README.md: rename, add md syntax, and major tweaks

From: Joe Konno <joe.konno(a)intel.com>

Make the README file a markdown document and rename accordingly. Add markdown syntax where needed. Rewrite the clunkiest bits, and add additional documentation where appropriate.

While in the file, made the project name (PowerTOP) consistent. Also removed some trailing spaces, hard-wrapped lines to 80 characters, and a few other low-hanging changes that made sense with markdown.

Note that a "Copyright and License" section was added. No changes to existing terms, but that section is needed for completeness.

Reviewed-by Doug Martin <doug.martin(a)intel.com>
Signed-off-by Joe Konno <joe.konno(a)intel.com>
---
 README    | 157 -----------------------------------------
 README.md | 204
++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 204 insertions(+), 157 deletions(-)  delete mode 100644

README create mode 100644 README.md

README deleted +0 -3
deleted file mode 100644
index a2c32ca79d9e..000000000000
@@ -1,157 +0,0 @@
-Build dependencies
-------------------
-PowerTOP uses C++, and expects g++ and libstdc++ to be functional -along

with a glibc/pthreadsi, autoconf, automake, and libtool in the -development environment.

README deleted +0 -10
-
-In addition to that, PowerTOP requires the following components:
-
-pciutils-devel (is only required if you have PCI) -ncurses-devel  (required)
-libnl-devel    (required)
-kernel version => 2.6.38
-
-Example packages to install in Ubuntu:
-
-sudo apt install libpci-dev libnl-3-dev libnl-genl-3-dev gettext \ -libgettextpo-

dev autopoint gettext libncurses5-dev libncursesw5-dev libtool-bin \ -dh- autoreconf autoconf-archive pkg-config

README deleted +0 -6
-
-Building & Installing PowerTOP
-------------------------------
-
-The autogen script is required to run only once to generate the configure for
-the build. Rest of the steps are required to run everytime there is a change -

made to the PowerTop.

README deleted +0 -8
-
-To build and install PowerTOP type the following commands,
-       ./autogen.sh
-       ./configure
-       make
-       sudo make install
-
-Note: For Android (running Intel Architecture ) there is a Android.mk -that

was provided by community members, and at this time is supported -mostly by community members.

README deleted +0 -25
-
-Build PowerTop for Android LollyPop
-------------------------------------
-
-1. Obtain pciutils and ncurses libraries.
-   Skip this step if they are already in the tree.
-
-   pciutils: Clone
-       https://github.com/trevd/android_external_pciutils
-   into external/pciutils
-
-   ncurses: Clone
-       https://github.com/cvpcs/android_external_libncurses
-   into external/ncurses
-
-2. Run
-       ./src/csstoh.sh src/powertop.css src/css.h
-   to generate the css.h header file.
-
-3. Apply patches inside patches/Android
-
-4. PowerTop can be built with top level make,
-   or by doing "mm".
-
-   The resulting binary is under

$ANDROID_PRODUCT_OUT/system/bin/powertop

README deleted +0 -6
-
-
-Kernel Parameters:
-------------------
-
-PowerTOP needs some kernel config options enabled in order function

properly.

README deleted +0 -23
-As of linux-3.3.0 these are (list probably incomplete):
-
-CONFIG_NO_HZ
-CONFIG_HIGH_RES_TIMERS
-CONFIG_HPET_TIMER
-CONFIG_CPU_FREQ_GOV_ONDEMAND
-CONFIG_USB_SUSPEND
-CONFIG_SND_AC97_POWER_SAVE
-CONFIG_TIMER_STATS
-CONFIG_PERF_EVENTS
-CONFIG_PERF_COUNTERS
-CONFIG_TRACEPOINTS
-CONFIG_TRACING
-CONFIG_EVENT_POWER_TRACING_DEPRECATED
-CONFIG_X86_MSR
-ACPI_PROCFS_POWER
-CONFIG_DEBUG_FS
-
-Use these configs from linux-3.13.rc1
-CONFIG_POWERCAP
-CONFIG_INTEL_RAPL
-
-The patches in the patches/ sub-directory are required for PowerTOP to

function -fully.

README deleted +0 -6
-
-
-
-Outputting a report
--------------------
-When invoking PowerTOP without arguments, PowerTOP starts in

interactive mode.

README deleted +0 -7
-However, for reporting bugs etc there is a special reporting modes:
-
-For an HTML formatted report simply execute PowerTOP with the following,
-
-powertop --html
-
-which will create a "powertop.html" file which is static and can be sent to -

others to help diagnose power issues. Additionally has the feature of showing -the tunables executions within the report as a reference.

README deleted +0 -2
-
-Note for the developers: If you make changes on the report format please -

make sure that the output can be cleanly validated by the W3C Markup - Validation Service and W3C CSS Validation Service:
- * http://validator.w3.org/#validate_by_upload
- * http://jigsaw.w3.org/css-validator/#validate_by_upload

README deleted +0 -6
-
-For a CSV formatted report, simply execute PowerTOP with the following,
-
-Powertop --csv
-
-which will create a “powertop.csv” file which is static and can be used in -

reporting, diagnoses, and analytical data analysis.

README deleted +0 -2
-
-Also you can set the number of iterations, and duration of test, in which

case -all reports will time stamp for you.

README deleted +0 -4
-
-Calibrating & Power Numbers
----------------------------
-PowerTOP will, when running on battery, track your power consumption as

well -as your activity on the system. Once there are sufficient such measurements, -PowerTOP can start to report power estimates for various activities.

README deleted +0 -6
-You can help get this estimation more accurate by running a calibration
-cycle:
-
-powertop --calibrate
-
-at least once; this will cycle through various display brightness levels -

(including "off") as well as USB device activities and some other workloads.

README deleted +0 -5
-
-
-Code from other open source projects
-------------------------------------
-PowerTOP contains some code from other open source projects; we'd like

to -thank the authors of those projects for their work.

README deleted +0 -3
-Specifically PowerTOP contains code from
-
-Parse Event Library - Copyright 2009, 2010 Red Hat Inc  Steven Rosted

<srostedt(a)redhat.com>
-nl80211 userspace tool - Copyright 2007, 2008 Johannes Berg
<johannes(a)sipsolutions.net>

README deleted +0 -5
-
-
-Extech Power Analyzer / Datalogger support
-------------------------------------------
-I use, and our analysis teams use, the Extech Power Analyzer/Datalogger -

(model number 380803) quite a lot, and PowerTOP supports using this - device over the serial cable. Just pass the device node on the command line - like this

README deleted +0 -4
-
-powertop --extech=/dev/ttyUSB0
-
-(where ttyUSB0 is the devicenode of the serial-to-usb adapter on my

system)

README deleted +0 -1
-
README.md new file +12 -0
new file mode 100644
index 000000000000..600cb545cbbf
@@ -0,0 +1,204 @@
+# PowerTOP
+
+PowerTOP is a Linux* tool used to diagnose issues with power
+consumption and power management. In addition to being a diagnostic
+tool, PowerTOP also has an interactive mode you can use to experiment
+with various power management settings, for cases where the Linux
+distribution has not enabled those settings.
+
+
+# Build dependencies
+
+PowerTOP is coded in C++. It was written for Linux-based operating

systems.

README.md new file +15 -0
+GNU* libc (`glibc`) and Linux `pthreads` are needed for PowerTOP to
+function properly. The GNU build system (`autoconf`, `automake`,
+`make`, `libtool`), as well as `gettext`, are required to build PowerTOP.
+
+In addition, PowerTOP requires the following:
+
+* kernel version => 2.6.38
+* `ncurses-devel` (required)
+* `libnl-devel` (required)
+* `pciutils-devel` (is only required if you have PCI)
+
+Example packages to install in Ubuntu*:
+
+    sudo apt install libpci-dev libnl-3-dev libnl-genl-3-dev gettext \
+    libgettextpo-dev autopoint gettext libncurses5-dev libncursesw5-dev

libtool-bin \

README.md new file +12 -0
+    dh-autoreconf autoconf-archive pkg-config
+
+
+# Building PowerTOP
+
+The `autogen.sh` script needs to be run only once to generate `configure`.
+You need to re-run it only if the build system configuration files
+(e.g. `configure.ac`) are modified. The remaining steps are required
+whenever source files are modified.
+
+To build PowerTOP from the cloned source, use the following commands:
+

README.md line 49

Quoted 10 lines
README.md new file +10 -0
+    ./autogen.sh
+    ./configure
+    make
+
+**Note:** For Android* (running on Intel® architecture) there is a
+Android.mk that was provided by community members, and at this time is
+supported mostly by community members.
+
+
+## Build PowerTOP for Android Lollipop

Are these instructions up to date? Just curious as we haven’t had a change to this section in a long time.

Quoted 169 lines
README.md new file +62 -0
+
+1. Obtain pciutils and ncurses libraries. Skip this step if they are already in
+   the tree.
+
+```
+pciutils: Clone
+    https://github.com/trevd/android_external_pciutils
+into external/pciutils
+
+ncurses: Clone
+    https://github.com/cvpcs/android_external_libncurses
+into external/ncurses
+```
+
+2. Run the following command to generate the `css.h` header file:
+    ./src/csstoh.sh src/powertop.css src/css.h
+
+3. Apply patches inside patches/Android
+
+4. PowerTOP can be built with top level make, or by doing `mm`.
+
+* The resulting binary is under
+`$ANDROID_PRODUCT_OUT/system/bin/powertop`
+
+
+# Kernel parameters
+
+PowerTOP needs some kernel config options enabled to function properly.
+As of linux-3.3.0, these are (the list probably is incomplete):
+
+    CONFIG_NO_HZ
+    CONFIG_HIGH_RES_TIMERS
+    CONFIG_HPET_TIMER
+    CONFIG_CPU_FREQ_GOV_ONDEMAND
+    CONFIG_USB_SUSPEND
+    CONFIG_SND_AC97_POWER_SAVE
+    CONFIG_TIMER_STATS
+    CONFIG_PERF_EVENTS
+    CONFIG_PERF_COUNTERS
+    CONFIG_TRACEPOINTS
+    CONFIG_TRACING
+    CONFIG_EVENT_POWER_TRACING_DEPRECATED
+    CONFIG_X86_MSR
+    ACPI_PROCFS_POWER
+    CONFIG_DEBUG_FS
+
+Use these configs from linux-3.13.rc1:
+
+    CONFIG_POWERCAP
+    CONFIG_INTEL_RAPL
+
+The patches in the `patches/` sub-directory are required for *full*
+PowerTOP functionality.
+
+
+# Outputting a report
+
+When PowerTOP is executed as root and without arguments, it runs in
+interactive mode. In this mode, PowerTOP most resembles `top`.
+
+For generating reports, or for filing functional bug reports, there are
+two output modes: CSV and HTML. You can set sample times, the number

of

README.md new file +40 -0
+iterations, a workload over which to run PowerTOP, and whether to
+include `debug`-level output.
+
+For an HTML report, execute PowerTOP with this option:
+
+    powertop --html=report.html
+
+This creates a static `report.html` file, suitable for sharing.
+
+For a CSV report, execute PowerTOP with this option:
+
+    powertop --csv=report.csv
+
+This creates a static `powertop.csv` file, also suitable for sharing.
+
+If you wish to file a functional bug report, generate and share a
+`debug`-mode HTML report and share it, using the following command:
+
+    powertop --debug --html=report.html
+
+**Important Note:** As PowerTOP is intended for privileged (`root`)
+use, your
+reports-- especially when run with `--debug`-- will contain verbose
+system information. PowerTOP **does not** sanitize, scrub, or otherwise
+anonymize its reports. Be mindful of this when sharing reports.
+
+**Developers:** If you make changes to the HTML reporting code,
+validate HTML output by using the W3C* Markup Validation Service and
+the W3C CSS Validation
+Service:
+* http://validator.w3.org/#validate_by_upload
+* http://jigsaw.w3.org/css-validator/#validate_by_upload
+
+
+# Calibrating and power numbers
+
+PowerTOP, when running on battery, tracks power consumption and
+activity on the system. Once there are sufficient measurements,
+PowerTOP can start to report power estimates for various activities.
+You can help increase the accuracy of the estimation by running a calibration

cycle at least once:

README.md new file +27 -0
+
+    powertop --calibrate
+
+*Calibration* entails cycling through various display brightness levels
+(including "off"), USB device activities, and other workloads.
+
+
+# Extech Power Analyzer / Datalogger support
+
+Our analysis teams use the Extech* Power Analyzer/Datalogger (model
+number 380803). PowerTOP supports this device over the serial cable by
+passing the device node on the command line using this command:
+
+    powertop --extech=/dev/ttyUSB0
+
+(where ttyUSB0 is the devicenode of the serial-to-usb adapter on our
+system)
+
+
+# Code from other open source projects
+
+PowerTOP contains some code from other open source projects; we'd like
+to thank the authors of those projects for their work. Specifically,
+PowerTOP contains code from
+
+```
+Parse Event Library - Copyright 2009, 2010 Red Hat Inc  Steven Rosted

<srostedt(a)redhat.com>
+nl80211 userspace tool - Copyright 2007, 2008 Johannes Berg
<johannes(a)sipsolutions.net>
+```

README.md new file +29 -1
+
+
+# Copyright and License
+
+    PowerTOP
+    Copyright (C) 2020  Intel Corporation
+
+    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 St, Fifth Floor, Boston, MA
+ 02110-1301  USA
+
+See `COPYING` file for a copy of the aforementioned (GPLv2) license.
+
+
+## SPDX Tag
+
+    /* SPDX-License-Identifier: GPL-2.0-only */
+
+From: https://spdx.org/licenses/GPL-2.0-only.html
--

2.26.2
_______________________________________________
PowerTop mailing list -- powertop(a)lists.01.org To unsubscribe send an email to powertop-leave(a)lists.01.org

author
#3 lore raw

[Powertop] Re: [PATCH 1/3 v1] README.md: rename, add md syntax, and major tweaks

On Wed, May 06, 2020 at 06:01:19PM +0000, Kammela, Gayatri wrote:

*** snip ***

Quoted 13 lines
Quoted 13 lines
README.md new file +13 -0
+
+# Building PowerTOP
+
+The `autogen.sh` script needs to be run only once to generate `configure`.
+You need to re-run it only if the build system configuration files
+(e.g. `configure.ac`) are modified. The remaining steps are required
+whenever source files are modified.
+
+To build PowerTOP from the cloned source, use the following commands:
+
+    ./autogen.sh
+    ./configure
+    make
Quoted 8 lines

README.md line 49

Quoted 7 lines
README.md new file +7 -0
+
+**Note:** For Android* (running on Intel® architecture) there is a
+Android.mk that was provided by community members, and at this time is
+supported mostly by community members.
+
+
+## Build PowerTOP for Android Lollipop

Are these instructions up to date? Just curious as we haven’t had a change to this section in a long time.

No, I did not verify the Android build instructions, I merely converted the existing instructions to markdown. In a subsequent submission, I hope to remove the Android build artifacts entirely, as we do not actively maintain them (and have not received community updates to them for a long time).

Quoted 17 lines
Quoted 17 lines
README.md new file +17 -0
+
+1. Obtain pciutils and ncurses libraries. Skip this step if they are already in
+   the tree.
+
+```
+pciutils: Clone
+    https://github.com/trevd/android_external_pciutils
+into external/pciutils
+
+ncurses: Clone
+    https://github.com/cvpcs/android_external_libncurses
+into external/ncurses
+```
+
+2. Run the following command to generate the `css.h` header file:
+    ./src/csstoh.sh src/powertop.css src/css.h
+
Quoted 8 lines

README.md line 73

Quoted 8 lines

+3. Apply patches inside patches/Android

README.md new file +7 -0
+
+4. PowerTOP can be built with top level make, or by doing `mm`.
+
+* The resulting binary is under
+`$ANDROID_PRODUCT_OUT/system/bin/powertop`
+
+

*** snip ***

author
#4 lore raw

PATCH 2/3 README.md: Fix a misspelled name

In reply to Joe Konno

From: Joe Konno <joe.konno(a)intel.com>

Sorry, Steven! Let's fix your last name, at long last.

Fixes #42
Signed-off-by: Joe Konno <joe.konno(a)intel.com>

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
README.md +1 -1
index 600cb545cbbf..a6a1259c582e 100644
@@ -171,7 +171,7 @@ the authors of those projects for their work. Specifically, PowerTOP contains
 code from
 
 ```
-Parse Event Library - Copyright 2009, 2010 Red Hat Inc  Steven Rosted <srostedt(a)redhat.com>
+Parse Event Library - Copyright 2009, 2010 Red Hat Inc  Steven Rostedt <srostedt(a)redhat.com>
 nl80211 userspace tool - Copyright 2007, 2008	Johannes Berg <johannes(a)sipsolutions.net>
 ```
 
Signature · 1 line
2.26.2
author
#5 lore raw

PATCH 3/3 Add CONTRIBUTE.md

In reply to Joe Konno

From: Joe Konno <joe.konno(a)intel.com>

It's time that PowerTOP had a contributors' guide.

Reviewed-by Doug Martin <doug.martin(a)intel.com>
Signed-off-by Joe Konno <joe.konno(a)intel.com>
---
 CONTRIBUTE.md | 188 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 188 insertions(+)
 create mode 100644 CONTRIBUTE.md
CONTRIBUTE.md new file +188 -0
new file mode 100644
index 000000000000..4287d41c854c
@@ -0,0 +1,188 @@
+# 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:
+* [Official Upstream Repository][upstream]
+
+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:
+* [Official Upstream Repository][upstream]
+
+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.
+* [CommonMark Specifications][cmark]
+
+The manual page uses roff syntax.
+* `man 7 roff`, or
+* [man 7 roff (in html)][manroff]
+
+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:
+* [Creating PO Files][gettext_create]
+
+The `gettext` project also has some links to commonly-used PO editors:
+* [Editing PO Files][gettext_edit]
+
+
+# Code conventions
+
+PowerTOP's maintainers will enforce the Linux* kernel coding style.
+* [Linux Kernel Coding Style][kernel_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][kernel_cos]
+
+
+# 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!
+
+
+[upstream]: https://github.com/fenrus75/powertop "Official PowerTOP Repository"
+[cmark]: https://spec.commonmark.org/ "External Link: CommonMark Specifications"
+[manroff]: http://man7.org/linux/man-pages/man7/roff.7.html "External Link: man 7 roff"
+[gettext_create]: https://www.gnu.org/software/gettext/manual/html_node/Creating.html#Creating "External Link: Creating a PO File"
+[gettext_edit]: https://www.gnu.org/software/gettext/manual/html_node/Editing.html#Editing "External Link: PO File Editors"
+[kernel_style]: https://www.kernel.org/doc/html/latest/process/coding-style.html "External Link: Linux kernel coding style"
+[kernel_cos]: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin "External Link: Developer's Certificate of Origin"
Signature · 1 line
2.26.2
#6 lore raw
In reply to Joe Konno
Quoted 21 lines

-----Original Message-----
From: Joe Konno <joe.konno(a)linux.intel.com>
Sent: Monday, May 4, 2020 9:50 AM
To: powertop(a)lists.01.org
Subject: [Powertop] [PATCH 0/3 v1] Rewrite README, and contribution guide

From: Joe Konno <joe.konno(a)intel.com>

This series rewrites the README using markdown syntax and adds a contribution guide.

Series was submitted as a GitHub pull request as well:
* https://github.com/fenrus75/powertop/pull/43

Thanks to my colleague, Doug Martin, for reviewing these changes.

CONTRIBUTE.md changes up development workflows in (hopefully) a good way. In my opinion, these are the key take-aways from that document:
* Use GitHub workflows for sharing/collaborating (e.g. PRs, Issues)
* Use the Linux kernel coding style

Quoted 7 lines

The README and CONTRIBUTE documents will continue to evolve, but this should get us going in the right direction.

PS: PowerTOP's project description on GitHub ("please post patches to the mailing list instead of using github pull requests") will be changed after this series is merged-- if it is.

Thanks for the series Joe! I only have one comment for the patch 1. Everything else looks good.

Quoted 20 lines

Joe Konno (3):
README.md: rename, add md syntax, and major tweaks README.md: Fix a misspelled name
Add CONTRIBUTE.md

 CONTRIBUTE.md | 188
++++++++++++++++++++++++++++++++++++++++++++++
 README        | 157 --------------------------------------
 README.md     | 204
++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 392 insertions(+), 157 deletions(-)  create mode 100644

CONTRIBUTE.md delete mode 100644 README create mode 100644 README.md

--
2.26.2
_______________________________________________
PowerTop mailing list -- powertop(a)lists.01.org To unsubscribe send an email to powertop-leave(a)lists.01.org