CONTRIBUTING

   1 0.INTRODUCTION
   2
   3   The FreeRADIUS project wouldn't exist without contributions from a significant number of developers.
   4
   5   We greatly value all comments, defect reports, patches/pull-requests, but must balance individual
   6   contributor's desires and practices against what's required for the project to operate efficiently.
   7
   8   This document describes best practices when interacting with members of the FreeRADIUS project team
   9   via GitHub.  If you follow these guidelines, it is very likely that your question, bug report or pull
  10   request will be acted on, and in a timely manor.
  11
  12   If you choose to ignore these guidelines our response will be a link to this document.
  13
  14
  15 1.GITHUB ISSUE TRACKER
  16
  17   The GitHub issue tracker is for non-security related defect reports, feature requests, and
  18   pull-requests ONLY.
  19
  20   It is not for support requests or questions regarding configuration/operation of the server, they
  21   belong on the users mailing list:
  22
  23     http://freeradius.org/list/users.html
  24
  25   Raising support requests or questions as issues will result in them being closed and locked.  If you
  26   continue to raise these questions as issues you will be banned from the FreeRADIUS project's GitHub
  27   repositories.
  28
  29   Security issues should be reported to security@freeradius.org, especially if they can be remotely
  30   exploited.  This ensures that patches can be developed before the exploit is made public.
  31
  32
  33 2.BEFORE REPORTING A DEFECT
  34
  35   Verify it's still present in the Git HEAD.  Checkout the appropriate branch for the version of the
  36   server you're working with as listed here (http://doc.freeradius.org), build the server, and attempt
  37   to reproduce your issue.
  38
  39   The ChangeLog (https://github.com/FreeRADIUS/freeradius-server/blob/v3.0.x/doc/ChangeLog) for the
  40   current stable branch may also be used to determine if your issue has already been addressed.
  41   The ChangeLog is updated as fixes are made to the server code, and usually reflects the state of the
  42   Git HEAD.
  43
  44   Do not report non-security defects for EOL branches (as listed on doc.freeradius.org), they will be
  45   closed and locked.
  46
  47
  48 3.CONTENTS OF A DEFECT REPORT
  49
  50   See doc/bugs (https://github.com/FreeRADIUS/freeradius-server/blob/master/doc/bugs) for information
  51   on what to include, and how to obtain it.
  52
  53   When logging bug reports using the GitHub issue tracker, pay attention to formatting.  You should
  54   ensure any log output is surrounded by two sets of tripple backticks (```).  If you don't do this
  55   Github will automatically link your issue to other pre-existing issues when it encounters a #<num>
  56   string.
  57
  58
  59 4.PULL REQUESTS AND CODING STANDARDS
  60
  61   If you're developing a new feature, module, or writing large amounts of code to fix a defect, contact
  62   a member of the FreeRADIUS development team first.  For simpler one or two line fixes, go ahead and
  63   open a pull-request immediately.
  64
  65   The dev team can be contacted via the devel mailing list (http://freeradius.org/list/devel.html),
  66   or via GitHub by using the GitHub issue tracker.
  67
  68   Contacting the dev team gives us the opportunity to offer feedback.  We may have a solution to your
  69   problem that doesn't require additional code, or may have ideas as to how your problem can be solved
  70   in a way that will better fit with the longterm vision for the server.
  71
  72   Once you've got the go ahead, read through the coding standards document:
  73
  74     http://wiki.freeradius.org/contributing/coding-standards
  75
  76   If you're creating a new module you may wish to read the module creation guide:
  77
  78     http://wiki.freeradius.org/contributing/Modules3
  79
  80   You may also wish to utilise the doxygen site to review code documentation:
  81
  82     http://doc.freeradius.org
  83
  84   The doxygen site contains the complete reference of all API functions with doxygen headers, as well
  85   as structs, and callback declarations.  doc.freeradius.org is updated within one minute of each commit
  86   to the master branch of the main freeradius-server repo.
  87
  88   Finally, this file was written to be displayed automatically on the GitHub issue tracker, so
  89   Git/GitHub knowledge is assumed.  If you're wondering what the heck a pull-request is, this
  90   document may be of some use:
  91
  92     http://wiki.freeradius.org/contributing/GitHub
  93
  94
  95 5.CONTINUOUS INTEGRATION TESTS
  96
  97   If possible include test cases in your pull-requests.
  98
  99   There are currently three test frameworks for different elements of the server:
 100
 101     Unit tests   - src/tests/unit/*.txt            - Tests for conditions and protocol encoders/decoders.
 102     Module tests - src/tests/modules/<module name> - Tests for module functionality.
 103     Unlang tests - src/tests/unlang/<test series>  - Tests for unlang keywords and functions.
 104
 105   See README.* docs in the directories above for basic information on writing test cases.  The easiest
 106   way to write new tests is to use the existing tests as examples.
 107
 108   Tests are run via Travis for each pull-request, and on every commit by a developer with repository
 109   access.