Junk

  • Revision slug: Sandbox
  • Revision title: NSPR Contributor's Guide
  • Revision id: 447693
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment

Revision Content

Abstract:

NSPR (NetScape Portable Runtime) accepts contributions in the form of bugfixes, new features, libraries, platform ports, documentation, test cases and other items from many sources. We (the NSPR module owners) sometimes disappoint our contributors when we reject their contributions. We reject contributions for a variety of reasons. Some of these reasons are not obvious to an outside observer. NSPR wishes to document some guidelines for those who would contribute to NSPR. These guidelines should help the contributor in crafting his contribution, increasing its likelihood for acceptance.

General Guidelines

Downward Compatibility. Applications other than the mozilla client, use the NSPR API. Therefore, the API must remain downward compatible across even major releases. This means that the behavior of an existing public API item in NSPR cannot change. Should you need to have a similar API, with some slightly different behavior or different function prototype, then suggest a new API with a different name.

C Language API. The NSPR API is a C Language API. Please do not contribute Java, C++ or other language wrappers.

Coding Style. NSPR does not have a documented coding style guide. Look at the extant code. Make yours look like that. Some guidelines concerning naming conventions can be found in NSPR Naming Conventions in the NSPR Reference. See also: XXX

Ownership of your contribution. When you contribute something to NSPR, you must have intellectual property rights to that contribution. This means that you cannot give us something you snatched from somewhere else. It must be your own invention, free and clear of encumberment of anyone or anything else; play close attention to the rights of your "Day-Job" employer. If you snatched it from somewhere else, tell us where; show us where the right to incorporate it into the NSPR exists.

License under MPL or GPL. When you contribute material to NSPR, you agree to allow your contribution to be licensed under the MPL or GPL.

BugFixes

Use Bugzilla to track bugs. Document the bug or use an existing report. Be verbose in describing what you are doing and why. Include your changes as differences in an attachment to the Bugzilla report.

Use a coding style consistent with the source file you are changing.

New Features

For purposes of this paper, a "new feature" is defined as some API addition that goes into the core NSPR library, for example: libnspr4.dll.

NSPR is mostly complete. New APIs are driven mostly by the OS vendors as they add new features. Should you decide that there's something that NSPR does not cover that should be covered, let's talk. Your proposed API should encapsulate a relatively low level capability as would be found in a system call or libc.

Your new feature must be implemented on all platforms supported by NSPR. When you consider a new API for NSPR ask yourself if your proposed feature can implement it across all platforms supported by NSPR. If several platforms cannot be made to implement your API, then it is not a good candidate for inclusion in NSPR.

Before you begin what may be a substantial effort in making a candidate feature for NSPR, talk to us. We may tell you that you have a good idea; we may say that it really is not a good candidate for inclusion in NSPR; we may give you suggestions on what would make it more generalized, hence a good candidate for inclusion in NSPR.

Use Bugzilla to track your work. Be verbose.

NSPR wants you to document your work. If we accept it, we are going to have to answer questions about it and/or maintain it. These are some guidelines for new APIs that you may add to NSPR.

Header File Descriptions. Provide header file descriptions that fully document your public typedefs, enums, macros, and functions.
See: prshm.h as an example of how your header file(s) should be documented.

Source File Descriptions. Provide descriptive documentation in your source (*.c) files. Alas, we have no source files documented as we think they should be.

The following are some general guidelines to use when implementing new features:

  • Don't export global variables.
  • Your code must be thread safe.
  • You must provide test cases that test all APIs you are adding. See: Test Cases.

New Libraries

All the guidelines applicable to New Features applies to new libraries.

For purposes of this paper, a "new library" is defined as a library under the mozilla/nsprpub/lib directory tree and built as a seperate library. These libraries exist, for the most part, as "legacy" code from NSPR 1.0 [Note that the current NSPR module owners do not now nor never have been involved with NSPR 1.0]. Such is life. That said: there are some libraries that implement functions intended for use with applications using NSPR, such as ...nsprpub/lib.libc/plgetopt.*.

  • Generally useful
  • Platform abstractions
  • You agree to sustain, bug fix
  • May rely on the NSPR API
  • May NOT rely on any other library API

New Platform Ports

  • All NSPR API items must be implemented
  • Platform specific headers in pr/include/md/_platformname.[h!cfg]
  • Platform specific code in pr/src/md/platform/*.c
  • Make rules in config/_platform.mk

Documentation

The files of NSPR's documentation are mantained using a proprietary word processing system [don't ask]. Document your work as described in New Features. Use the style of other NSPR documentation. We will see that your documentation is transcribed into the appropriate word processor and the derived HTML shows up on mozilla.org.

Test Cases

You should provide test cases for all new features and new libraries.

Give consideration to providing a test case when fixing a bug if an existing test case did not catch a bug it should have caught.

The new test cases should be implemented in the style of other NSPR test cases.

Test cases should prove that added API items work as advertized.

Test cases should serve as an example of how to use the API items.

Test cases should provoke failure of every API item and report its failure.

Frequently Ask Questions (FAQ)

Q: Why was my contribution rejected?
A: Check the Bugzilla report covering your contribution.

Last Update: $Id: contributors.html 48936 2009-08-11 14:45:57Z
mike@silverorange.com $

my-sample

HTML Content

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
  </head>

  <body>
    <section id="example">
      <input id ="greetme" type="button" name="submitButton" value="Greet Me!" />
      <input id ="user" type="text" name="submitButton" value="" />
      <div id="welcome"></div>
    </section>
    <script type="text/javascript" src="js/main.js"></script>
  </body>

</html>

CSS Content

body {border: solid 1px;}
#example {padding: 10px;}
#welcome {padding: 5px 0 0 0;}

JavaScript Content

function makeGreeting() {
  var user = document.getElementById('user');
  var greeting = "Hi, " + user.value + "!";
  return greeting;
}

var greetme = document.getElementById('greetme');

greetme.onclick = function() {
  var welcome = document.getElementById('welcome');
  welcome.textContent = makeGreeting();
}

{{ EmbedLiveSample('my-sample') }}

 

Moar stuff

Once you've configured Firefox and Firefox OS for debugging support, you can use the Remote Debugger
  to debug your code running on a Firefox OS device or on the Firefox OS Simulator.
In order to debug JavaScript running on a Firefox OS or Android device,  
you'll need to be sure the device is connected to a USB port and that lsusb and adb can see it.  
  Then you need to forward the appropriate TCP port to the device
by opening a terminal window and issuing the following command:  

 

 

 

 

On the Android device On the desktop
 
 
 

Now open up a command shell. Android Platform Tools will have installed adb in the "platform-tools" directory under the directory in which you installed the Android SDK. Make sure the "platform-tools" directory is in your path. Then type:
 

adb devices


You should see some output like:

List of devices attached
51800F220F01564 device

(The long hex string will be different.)

If you do, then adb has found your device and you can get started.

Revision Source

<p><strong>Abstract: </strong></p>
<p>NSPR (NetScape Portable Runtime) accepts contributions in the form of bugfixes, new features, libraries, platform ports, documentation, test cases and other items from many sources. We (the NSPR module owners) sometimes disappoint our contributors when we reject their contributions. We reject contributions for a variety of reasons. Some of these reasons are not obvious to an outside observer. NSPR wishes to document some guidelines for those who would contribute to NSPR. These guidelines should help the contributor in crafting his contribution, increasing its likelihood for acceptance.</p>
<h2 id="General_Guidelines"><a name="General Guidelines">General Guidelines</a></h2>
<p><strong><u>Downward Compatibility.</u></strong> Applications other than the mozilla client, use the NSPR API. Therefore, the API must remain downward compatible across even major releases. This means that the behavior of an existing public API item in NSPR cannot change. Should you need to have a similar API, with some slightly different behavior or different function prototype, then suggest a new API with a different name.</p>
<p><strong><u>C Language API.</u></strong> The NSPR API is a C Language API. Please do not contribute Java, C++ or other language wrappers.</p>
<p><strong><u>Coding Style.</u></strong> NSPR does not have a documented coding style guide. Look at the extant code. Make yours look like that. Some guidelines concerning naming conventions can be found in <a href="http://www.mozilla.org/projects/nspr/reference/html/printro.html" title="http://www.mozilla.org/projects/nspr/reference/html/printro.html">NSPR Naming Conventions</a> in the <a href="http://www.mozilla.org/projects/nspr/reference/html/index.html" title="http://www.mozilla.org/projects/nspr/reference/html/index.html">NSPR Reference</a>. See also: XXX</p>
<p><strong><u>Ownership of your contribution. </u></strong>When you contribute something to NSPR, you must have intellectual property rights to that contribution. This means that you cannot give us something you snatched from somewhere else. It must be your own invention, free and clear of encumberment of anyone or anything else; play close attention to the rights of your "Day-Job" employer. If you snatched it from somewhere else, tell us where; show us where the right to incorporate it into the NSPR exists.</p>
<p><strong><u>License under MPL or GPL.</u></strong> When you contribute material to NSPR, you agree to allow your contribution to be licensed under the MPL or GPL.</p>
<h2 id="BugFixes"><a name="BugFixes">BugFixes</a></h2>
<p>Use <a href="https://bugzilla.mozilla.org/" title="https://bugzilla.mozilla.org/">Bugzilla</a> to track bugs. Document the bug or use an existing report. Be verbose in describing what you are doing and why. Include your changes as differences in an attachment to the Bugzilla report.</p>
<p>Use a coding style consistent with the source file you are changing.</p>
<h2 id="New_Features"><a name="New Features">New Features</a></h2>
<p>For purposes of this paper, a "new feature" is defined as some API addition that goes into the core NSPR library, for example: libnspr4.dll.</p>
<p>NSPR is mostly complete. New APIs are driven mostly by the OS vendors as they add new features. Should you decide that there's something that NSPR does not cover that should be covered, let's talk. Your proposed API should encapsulate a relatively low level capability as would be found in a system call or libc.</p>
<p>Your new feature must be implemented on all platforms supported by NSPR. When you consider a new API for NSPR ask yourself if your proposed feature can implement it across all platforms supported by NSPR. If several platforms cannot be made to implement your API, then it is not a good candidate for inclusion in NSPR.</p>
<p>Before you begin what may be a substantial effort in making a candidate feature for NSPR, talk to us. We may tell you that you have a good idea; we may say that it really is not a good candidate for inclusion in NSPR; we may give you suggestions on what would make it more generalized, hence a good candidate for inclusion in NSPR.</p>
<p>Use <a href="https://bugzilla.mozilla.org/" title="https://bugzilla.mozilla.org/">Bugzilla</a> to track your work. Be verbose.</p>
<p>NSPR wants you to document your work. If we accept it, we are going to have to answer questions about it and/or maintain it. These are some guidelines for new APIs that you may add to NSPR.</p>
<p><strong>Header File Descriptions. </strong>Provide header file descriptions that fully document your public typedefs, enums, macros, and functions.<br />
  See: <a href="http://lxr.mozilla.org/nspr/source/nsprpub/pr/include/prshm.h" title="http://lxr.mozilla.org/nspr/source/nsprpub/pr/include/prshm.h">prshm.h</a> as an example of how your header file(s) should be documented.</p>
<p><strong>Source File Descriptions.</strong> Provide descriptive documentation in your source (*.c) files. Alas, we have no source files documented as we think they should be.</p>
<p>The following are some general guidelines to use when implementing new features:</p>
<ul>
  <li>Don't export global variables.</li>
  <li>Your code must be thread safe.</li>
  <li>You must provide test cases that test all APIs you are adding. See: <a href="#Test Cases" title="#Test Cases">Test Cases</a>.</li>
</ul>
<h2 id="New_Libraries"><a name="New Libraries">New Libraries</a></h2>
<p>All the guidelines applicable to <a href="#New Libraries" title="#New Libraries">New Features</a> applies to new libraries.</p>
<p>For purposes of this paper, a "new library" is defined as a library under the mozilla/nsprpub/lib directory tree and built as a seperate library. These libraries exist, for the most part, as "legacy" code from NSPR 1.0 [Note that the current NSPR module owners do not now nor never have been involved with NSPR 1.0]. Such is life. That said: there are some libraries that implement functions intended for use with applications using NSPR, such as ...nsprpub/lib.libc/plgetopt.*.</p>
<ul>
  <li>Generally useful</li>
  <li>Platform abstractions</li>
  <li>You agree to sustain, bug fix</li>
  <li>May rely on the NSPR API</li>
  <li>May NOT rely on any other library API</li>
</ul>
<h2 id="New_Platform_Ports"><a name="New Platform Ports">New Platform Ports</a></h2>
<ul>
  <li>All NSPR API items must be implemented</li>
  <li>Platform specific headers in pr/include/md/_platformname.[h!cfg]</li>
  <li>Platform specific code in pr/src/md/platform/*.c</li>
  <li>Make rules in config/_platform.mk</li>
</ul>
<h2 id="Documentation"><a name="Documentation">Documentation</a></h2>
<p>The files of NSPR's documentation are mantained using a proprietary word processing system [don't ask]. Document your work as described in <a href="#New Features" title="#New Features">New Features</a>. Use the style of other NSPR documentation. We will see that your documentation is transcribed into the appropriate word processor and the derived HTML shows up on mozilla.org.</p>
<h2 id="Test_Cases"><a name="Test Cases">Test Cases</a></h2>
<p>You should provide test cases for all new features and new libraries.</p>
<p>Give consideration to providing a test case when fixing a bug if an existing test case did not catch a bug it should have caught.</p>
<p>The new test cases should be implemented in the style of other NSPR test cases.</p>
<p>Test cases should prove that added API items work as advertized.</p>
<p>Test cases should serve as an example of how to use the API items.</p>
<p>Test cases should provoke failure of every API item and report its failure.</p>
<h2 id="Frequently_Ask_Questions_(FAQ)"><a name="FAQ">Frequently Ask Questions (FAQ)</a></h2>
<p>Q: Why was my contribution rejected?<br />
  A: Check the Bugzilla report covering your contribution.</p>
<p>Last Update: $Id: contributors.html 48936 2009-08-11 14:45:57Z<br />
  mike@silverorange.com $</p>
<h2 id="my-sample" name="my-sample">my-sample</h2>
<h3 id="HTML_Content">HTML Content</h3>
<pre class="brush: html">
&lt;!DOCTYPE html&gt;
&lt;html&gt;
&nbsp; &lt;head&gt;
&nbsp;&nbsp;&nbsp; &lt;meta charset="UTF-8"&gt;
&nbsp; &lt;/head&gt;

&nbsp; &lt;body&gt;
    &lt;section id="example"&gt;
  &nbsp;&nbsp;&nbsp; &lt;input id ="greetme" type="button" name="submitButton" value="Greet Me!" /&gt;
&nbsp;&nbsp;  &nbsp; &lt;input id ="user" type="text" name="submitButton" value="" /&gt;
&nbsp;&nbsp;&nbsp;   &lt;div id="welcome"&gt;&lt;/div&gt;
    &lt;/section&gt;
&nbsp;&nbsp;&nbsp; &lt;script type="text/javascript" src="js/main.js"&gt;&lt;/script&gt;
&nbsp; &lt;/body&gt;

&lt;/html&gt;

</pre>
<h3 id="CSS_Content">CSS Content</h3>
<pre class="brush: css">
body {border: solid 1px;}
#example {padding: 10px;}
#welcome {padding: 5px 0 0 0;}
</pre>
<h3 id="JavaScript_Content">JavaScript Content</h3>
<pre class="brush: js">
function makeGreeting() {
&nbsp; var user = document.getElementById('user');
&nbsp; var greeting = "Hi, " + user.value + "!";
&nbsp; return greeting;
}

var greetme = document.getElementById('greetme');

greetme.onclick = function() {
&nbsp; var welcome = document.getElementById('welcome');
&nbsp; welcome.textContent = makeGreeting();
}</pre>
<p>{{ EmbedLiveSample('my-sample') }}</p>
<p>&nbsp;</p>
<h2 id="Moar_stuff">Moar stuff</h2>
<table style="border-width:0">
  <tbody>
    <tr>
      <td style="border-width:0">Once you've <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Debugging/Setting_up" title="/en-US/docs/Mozilla/Firefox_OS/Debugging/Setting_up">configured Firefox and Firefox OS for debugging support</a>,</td>
      <td style="border-width:0">you can use the Remote Debugger</td>
    </tr>
    <tr>
      <td style="border-width:0">&nbsp;</td>
      <td style="border-width:0">to debug your code running on a Firefox OS device or on the Firefox OS Simulator.</td>
    </tr>
    <tr>
      <td style="border-width:0">In order to debug JavaScript running on a Firefox OS or Android device,</td>
      <td style="border-width:0">&nbsp;</td>
    </tr>
    <tr>
      <td style="border-width:0">you'll need to be sure the device is connected to a USB port and that <code>lsusb</code> and <code>adb</code> can see it.</td>
      <td style="border-width:0">&nbsp;</td>
    </tr>
    <tr>
      <td style="border-width:0">&nbsp;</td>
      <td style="border-width:0">Then you need to forward the appropriate TCP port to the device</td>
    </tr>
    <tr>
      <td style="border-width:0">by opening a terminal window and issuing the following command:</td>
      <td style="border-width:0">&nbsp;</td>
    </tr>
  </tbody>
</table>
<p>&nbsp;</p>
<p>&nbsp;</p>
<p>&nbsp;</p>
<p>&nbsp;</p>


<table style="border-width:0; table-layout:fixed">
  <colgroup>
    <col width="50%" />
    <col width="50%" />
  </colgroup>
  <thead>
    <tr>
      <th scope="col" style="width:50%;">On the Android device</th>
      <th scope="col" style="width:50%;">On the desktop</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="border-width:0; border-right-width:1px">&nbsp;</td>
      <td style="border-width:0">
        <ul>
          <li>Install the correct version of the <a href="http://developer.android.com/sdk/index.html" title="http://developer.android.com/sdk/index.html">Android SDK</a> for your device.</li>
          <li>Using the Android SDK, install the <a href="http://developer.android.com/sdk/installing.html#components" title="http://developer.android.com/sdk/installing.html#components">Android Platform Tools</a>.</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td style="border-width:0; border-right-width:1px">
        <ul>
          <li><a href="http://developer.android.com/guide/developing/device.html#setting-up" title="http://developer.android.com/guide/developing/device.html#setting-up">Enable USB debugging (step 2 of this link only)</a>.</li>
          <li>Attach the device to the desktop via USB.</li>
        </ul>
      </td>
      <td style="border-width:0">&nbsp;</td>
    </tr>
    <tr>
      <td style="border-width:0; border-right-width:1px">&nbsp;</td>
      <td style="border-width:0">
        <p>Now open up a command shell. Android Platform Tools will have installed adb in the "platform-tools" directory under the directory in which you installed the Android SDK. Make sure the "platform-tools" directory is in your path. Then type:<br />
          &nbsp;</p>
        <pre>
adb devices</pre>
        <p><br />
          You should see some output like:</p>
        <pre>
List of devices attached
51800F220F01564 device
</pre>
        <p>(The long hex string will be different.)</p>
        <p>If you do, then <code>adb</code> has found your device and you can get started.</p>
      </td>
    </tr>
  </tbody>
</table>
Revert to this revision