Re: Write-up on submitting systemtap examples

[Jim Keniston <jkenisto@us.ibm.com>]

On Mon, 2009-05-11 at 10:43 -0400, William Cohen wrote:
> Hi All,
> 
> Trying to streamline the process of people submitting systemtap examples. Below
> is a writeup trying to cover what to do for submitting examples. Comments on it
> would be appreciated. Expect that this text would go in the
> testsuite/systemtap.examples directory and be like the HACKING file in the root
> of systemtap source code.
> 
> -Will

Looks good.  See below for suggested tweaks.  Thanks for your work on
this.

Jim

> 
> 
> The text describes contribution procedures for added scripts to

s/added/adding/ ?

> systemtap.examples.  Please read before submitting Systemtap examples.
> Discussions take place on the <systemtap@sources.redhat.com> mailing
> list.
> 
> - general
> 
> The script should do something that a normal users of SystemTap might

Fix "a normal users".

> like to do, such as show which processes have systemcalls that timeout

s/systemcalls/system calls/
s/timeout/time out/	-- since it's a verb here

> or show which memory accesses cause page faults.  Scripts that check
> that check some aspect of systemtap operates correctly, but would

s/that check that check/that check that/

> never be used by a regular user should go in one of the other test
> directories.
> 
> - copyright
> 
>   You must designate the appropriate copyright holder for your
>   contribution.  If not already there, this name should be added by

I'm not sure what you mean by "this name".

>   your patch to the copyright header in the affected files.  The
>   copyright holder is assumed to agree with the general licensing
>   terms (GPLv2+).
> 
> - coding style
> 
>   Abide by the general formatting of the code you are modifying.  The
>   code base generally follows the GNU standards in usermode code and
>   the Linux kernel standards in runtime code.
> 
>   - Try to keep the lines shorter than 80 characters long

These are complete sentences, so append periods.

>   - Make use of systemtap functions to factor out common idoms in code

s/idoms/idioms/

>   - Use tapset probe points rather than raw function names
>   - No probes by file and line number allowed in examples
>   - Avoid using guru mode (-g) in the examples
>   - Minimize use of globals variables:
>  	All associative arrays must be global in SystemTap
> 	Variables used only for the duration of a probe should be local
>   - Make the file executable and use the following line at the
>     beginning of the script to select the proper interpreter:
> 
>     #! /usr/bin/env stap
> 
> - Describe the example
> 
>   Each example script has a description in a .meta file that provide
>   an easy-to-parse format that describes various aspect of the example
>   script. The .meta file has the same base name as the example script.
>   The .meta file is parsed to generate an webpage listing all the

s/an webpage/a web page/

>   available examples; the webpage is available at:
>   http://sourceware.org/systemtap/examples/.  The .meta file also
>   describe how to run the compile example script for testing. This

s/describe/describes/
s/compile/compiled/

>   ensures that the example is frequently run to verified it works on a
>   wide range fo platforms.
> 
>    Each line in the .meta file has a tag indicate what the line is.

s/tag indicate/tag to indicate/

>   You can look at the meta files for the existing systemtap examples

s/meta/.meta/ to match elsewhere?
Capitalization of SystemTap is inconsistent.

>   in the SystemTap source code repository.  For more information about
>   the tags refer to the email thread archived at:
> 
>   http://sourceware.org/ml/systemtap/2008-q2/msg00045.html
> 
> 
> - Review, revision, and submission of the example script
> 
>   When you have a SystemTap script that should be included as an
>   example, submit it to the SystemTap mailing list,
>   systemtap@sources.redhat.com for review. Even if the script is not
>   ready for submission as an example, feel free to ask questions or
>   discuss the work-in-progress script with other people working with
>   SystemTap.
>