CONTRIBUTING.md

   1 All functionality should be available in pure Python. Optional C
   2 implementations may be written for performance reasons, but should never
   3 replace the Python implementation. The C implementations should follow the
   4 kernel/git coding style.
   5
   6 Where possible include updates to NEWS along with your improvements.
   7
   8 New functionality and bug fixes should be accompanied by matching unit tests.
   9
  10 Coding style
  11 ------------
  12 Where possible, please follow PEP8 with regard to coding style.
  13
  14 Furthermore, triple-quotes should always be """, single quotes are ' unless
  15 using " would result in less escaping within the string.
  16
  17 Public methods, functions and classes should all have doc strings. Please use
  18 epydoc style docstrings to document parameters and return values.
  19 You can generate the documentation by running "make doc".
  20
  21 Running the tests
  22 -----------------
  23 To run the testsuite, you should be able to simply run "make check". This
  24 will run the tests using unittest.
  25
  26  $ make check
  27
  28 Tox configuration is also present as well as a Travis configuration file.
  29
  30 String Types
  31 ------------
  32 Like Linux, Git treats filenames as arbitrary bytestrings. There is no prescribed
  33 encoding for these strings, and although it is fairly common to use UTF-8, any
  34 raw byte strings are supported.
  35
  36 For this reason, Dulwich internally treats git-based filenames as bytestrings.
  37 It is up to the Dulwich API user to encode and decode them if necessary. In the
  38 future, the porcelain may accept unicode strings and convert them to bytestrings
  39 as necessary on the fly (using sys.getfilesystemencoding()).
  40
  41 * git-repository related filenames: bytes
  42 * object sha1 digests (20 bytes long): bytes
  43 * object sha1 hexdigests (40 bytes long): str (bytestrings on python2, strings
  44   on python3)
  45
  46 Merge requests
  47 --------------
  48 Please either send pull requests to the maintainer (jelmer@jelmer.uk) or create
  49 new pull requests on GitHub.
  50
  51 Licensing
  52 ---------
  53 All contributions should be made under the same license that Dulwich itself
  54 comes under: both Apache License, version 2.0 or later and GNU General Public
  55 License, version 2.0 or later.