CONTRIBUTING.rst 2.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657
  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. Where possible include updates to NEWS along with your improvements.
  6. New functionality and bug fixes should be accompanied by matching unit tests.
  7. Coding style
  8. ------------
  9. Where possible, please follow PEP8 with regard to coding style. Run flake8.
  10. Furthermore, triple-quotes should always be """, single quotes are ' unless
  11. using " would result in less escaping within the string.
  12. Public methods, functions and classes should all have doc strings. Please use
  13. Google style docstrings to document parameters and return values.
  14. You can generate the documentation by running "make doc".
  15. Running the tests
  16. -----------------
  17. To run the testsuite, you should be able to simply run "make check". This
  18. will run the tests using unittest.
  19. ::
  20. $ make check
  21. Tox configuration is also present.
  22. String Types
  23. ------------
  24. Like Linux, Git treats filenames as arbitrary bytestrings. There is no prescribed
  25. encoding for these strings, and although it is fairly common to use UTF-8, any
  26. raw byte strings are supported.
  27. For this reason, the lower levels in Dulwich treat git-based filenames as
  28. bytestrings. It is up to the Dulwich API user to encode and decode them if
  29. necessary. The porcelain may accept unicode strings and convert them to
  30. bytestrings as necessary on the fly (using 'utf-8').
  31. * on-disk filenames: regular strings, or ideally, pathlib.Path instances
  32. * git-repository related filenames: bytes
  33. * object sha1 digests (20 bytes long): bytes
  34. * object sha1 hexdigests (40 bytes long): str (bytestrings on python2, strings
  35. on python3)
  36. Merge requests
  37. --------------
  38. Please either send pull requests to the maintainer (jelmer@jelmer.uk) or create
  39. new pull requests on GitHub.
  40. Licensing
  41. ---------
  42. All contributions should be made under the same license that Dulwich itself
  43. comes under: both Apache License, version 2.0 or later and GNU General Public
  44. License, version 2.0 or later.