docs/nspr/nspr_contributor_guide.rst

   1 NSPR contributor guide
   2 ======================
   3
   4 **Abstract:**
   5
   6    NSPR accepts contributions in the form of bugfixes, new features,
   7    libraries, platform ports, documentation, test cases and other items
   8    from many sources. We (the NSPR module owners) sometimes disappoint
   9    our contributors when we must reject their contributions. We reject
  10    contributions for a variety of reasons. Some of these reasons are not
  11    obvious to an outside observer. NSPR wishes to document some
  12    guidelines for those who would contribute to NSPR. These guidelines
  13    should help the contributor in crafting his contribution, increasing
  14    its likelihood for acceptance.
  15
  16 General Guidelines
  17 ~~~~~~~~~~~~~~~~~~
  18
  19 *Downward Compatibility*
  20 ^^^^^^^^^^^^^^^^^^^^^^^^
  21
  22 Because many different applications, besides the mozilla client, use the
  23 NSPR API, the API must remain downward compatible across even major
  24 releases. This means that the behavior of an existing public API item in
  25 NSPR cannot change. Should you need to have a similar API, with some
  26 slightly different behavior or different function prototype, then
  27 suggest a new API with a different name.
  28
  29 *C Language API*
  30 ^^^^^^^^^^^^^^^^
  31
  32 The NSPR API is a C Language API. Please do not contribute Java, C or
  33 other language wrappers.
  34
  35 *Coding Style*
  36 ^^^^^^^^^^^^^^
  37
  38 NSPR does not have a documented coding style guide. Look at the extant
  39 code. Make yours look like that. Some guidelines concerning naming
  40 conventions can be found in :ref:`NSPR_Naming_Conventions`.
  41 in the :ref:`NSPR API Reference`.
  42
  43 *Ownership of your contribution*
  44 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  45
  46 When you contribute something to NSPR, you must have intellectual
  47 property rights to that contribution. This means that you cannot give us
  48 something you snatched from somewhere else;. it must be your own
  49 invention, free and clear of encumberment of anyone or anything else;
  50 pay close attention to the rights of your "Day-Job" employer. If you
  51 snatched it from somewhere else, tell us where; show us where the right
  52 to incorporate it into NSPR exists.
  53
  54 *License under MPL or GPL*
  55 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  56
  57 When you contribute material to NSPR, you agree to allow your
  58 contribution to be licensed under the MPL or GPL.
  59
  60 BugFixes
  61 ~~~~~~~~
  62
  63 Use `Bugzilla <https://bugzilla.mozilla.org/>`__ to track bugs. Document
  64 the bug or use an existing report. Be verbose in describing what you are
  65 doing and why.
  66
  67 Include your changes as diffs in an attachment to the BugZilla report.
  68
  69 Use a coding style consistent with the source file you are changing.
  70
  71 New Features
  72 ~~~~~~~~~~~~
  73
  74 For purposes of this paper, a "new feature" is defined as some API
  75 addition that goes into the core NSPR library, for example:
  76 ``libnspr4.dll``
  77
  78 NSPR is mostly complete. New APIs are driven mostly by the OS vendors as
  79 they add new features. Should you decide that there's something that
  80 NSPR does not cover that should be covered, let's talk. Your proposed
  81 API should encapsulate a relatively low level capability as would be
  82 found in a system call or libc.
  83
  84 Your new feature must be implemented on all platforms supported by NSPR.
  85 When you consider a new API for NSPR ask yourself if your proposed
  86 feature can implement it across all platforms supported by NSPR. If
  87 several platforms cannot be made to implement your API, then it is not a
  88 good candidate for inclusion in NSPR.
  89
  90 Before you begin what may be a substantial effort in making a candidate
  91 feature for NSPR, talk to us. We may tell you that you have a good idea;
  92 we may say that it really is not a good candidate for inclusion in NSPR;
  93 we may give you suggestions on what would make it more generalized,
  94 hence a good candidate for inclusion in NSPR.
  95
  96 Use `Bugzilla <https://bugzilla.mozilla.org>`__ to track your work. Be
  97 verbose.
  98
  99 NSPR wants you to document your work. If we accept it, we are going to
 100 have to answer questions about it and/or maintain it. These are some
 101 guidelines for new APIs that you may add to NSPR.
 102
 103 **Header File Descriptions**. Provide header file descriptions that
 104 fully document your public typedefs, enums, macros and functions.
 105
 106 See:
 107 `prshm.h <http://lxr.mozilla.org/nspr/source/nsprpub/pr/include/prshm.h>`__
 108 as an example of how your header file(s) should be documented.
 109
 110 *Source File Descriptions*o. Provide descriptive documentation in your
 111 source (*.c) files. Alas, we have no source files documented as we think
 112 they should be.
 113
 114 The following are some general guidelines to use when implementing new
 115 features:
 116
 117 -  Don't export global variables
 118 -  Your code must be thread safe
 119 -  You must provide test cases that test all APIs you are adding. See:
 120    [#TestCases Test Cases]
 121
 122 New Libraries
 123 ~~~~~~~~~~~~~
 124
 125 All the guidelines applicable to [#NewFeatures New Features] applies to
 126 new libraries.
 127
 128 For purposes of this paper, a "new library" is defined as a library under
 129 the ``mozilla/nsprpub/lib`` directory tree and built as a separate
 130 library. These libraries exist, for the most part, as "legacy" code from
 131 NSPR 1.0. [Note that the current NSPR module owners do not now nor never
 132 have been involved with NSPR 1.0.]. Such is life. That said: There are
 133 some libraries that implement functions intended for use with
 134 applications using NSPR, such as ``...nsprpub/lib/libc/plgetopt.*.``
 135
 136 -  generally useful
 137 -  platform abstractions
 138 -  you agree to sustain, bug fix
 139 -  May rely on the NSPR API
 140 -  May NOT rely on any other library API
 141
 142 New Platform Ports
 143 ~~~~~~~~~~~~~~~~~~
 144
 145 -  all NSPR API items must be implemented
 146 -  platform specific headers in ``pr/include/md/_platformname.[h!cfg]``
 147 -  platform specific code in ``pr/src/md/platform/*.c``
 148 -  make rules in ``config/_platform.mk``
 149
 150 Documentation
 151 ~~~~~~~~~~~~~
 152
 153 The files for NSPR's documentation are maintained using a proprietary
 154 word processing system [don't ask]. Document your work as described in
 155 [#NewFeatures New Features]. Use the style of other NSPR documentation.
 156 We will see that your documentation is transcribed into the appropriate
 157 word processor and the derived HTML shows up on mozilla.org
 158
 159 Test Cases
 160 ~~~~~~~~~~
 161
 162 You should provide test cases for all new features and new libraries.
 163
 164 Give consideration to providing a test case when fixing a bug if an
 165 existing test case did not catch a bug it should have caught.
 166
 167 The new test cases should be implemented in the style of other NSPR test
 168 cases.
 169
 170 Test cases should prove that the added API items work as advertised.
 171
 172 Test cases should serve as an example of how to use the API items.
 173
 174 Test cases should provoke failure of every API item and report its
 175 failure.
 176
 177 Frequently Asked Questions (FAQ)
 178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 179
 180 **Q:** Why was my contribution rejected?
 181
 182 **A:** Check the Bugzilla report covering your contribution.