diff options
Diffstat (limited to 'CONTRIBUTING')
| -rw-r--r-- | CONTRIBUTING | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/CONTRIBUTING b/CONTRIBUTING new file mode 100644 index 0000000..28a0d87 --- /dev/null +++ b/CONTRIBUTING @@ -0,0 +1,109 @@ +0.INTRODUCTION + + The FreeRADIUS project wouldn't exist without contributions from a significant number of developers. + + We greatly value all comments, defect reports, patches/pull-requests, but must balance individual + contributor's desires and practices against what's required for the project to operate efficiently. + + This document describes best practices when interacting with members of the FreeRADIUS project team + via GitHub. If you follow these guidelines, it is very likely that your question, bug report or pull + request will be acted on, and in a timely manor. + + If you choose to ignore these guidelines our response will be a link to this document. + + +1.GITHUB ISSUE TRACKER + + The GitHub issue tracker is for non-security related defect reports, feature requests, and + pull-requests ONLY. + + It is not for support requests or questions regarding configuration/operation of the server, they + belong on the users mailing list: + + https://freeradius.org/support/ + + Raising support requests or questions as issues will result in them being closed and locked. If you + continue to raise these questions as issues you will be banned from the FreeRADIUS project's GitHub + repositories. + + Security issues should be reported to security@freeradius.org, especially if they can be remotely + exploited. This ensures that patches can be developed before the exploit is made public. + + +2.BEFORE REPORTING A DEFECT + + Verify it's still present in the Git HEAD. Checkout the appropriate branch for the version of the + server you're working with as listed here (http://doc.freeradius.org), build the server, and attempt + to reproduce your issue. + + The ChangeLog (https://github.com/FreeRADIUS/freeradius-server/blob/v3.2.x/doc/ChangeLog) for the + current stable branch may also be used to determine if your issue has already been addressed. + The ChangeLog is updated as fixes are made to the server code, and usually reflects the state of the + Git HEAD. + + Do not report non-security defects for EOL branches (as listed on doc.freeradius.org), they will be + closed and locked. + + +3.CONTENTS OF A DEFECT REPORT + + See doc/bugs (https://github.com/FreeRADIUS/freeradius-server/blob/v3.2.x/doc/bugs) for information + on what to include, and how to obtain it. + + When logging bug reports using the GitHub issue tracker, pay attention to formatting. You should + ensure any log output is surrounded by two sets of tripple backticks (```). If you don't do this + Github will automatically link your issue to other pre-existing issues when it encounters a #<num> + string. + + +4.PULL REQUESTS AND CODING STANDARDS + + If you're developing a new feature, module, or writing large amounts of code to fix a defect, contact + a member of the FreeRADIUS development team first. For simpler one or two line fixes, go ahead and + open a pull-request immediately. + + The dev team can be contacted via the devel mailing list (https://freeradius.org/support/), + or via GitHub by using the GitHub issue tracker. + + Contacting the dev team gives us the opportunity to offer feedback. We may have a solution to your + problem that doesn't require additional code, or may have ideas as to how your problem can be solved + in a way that will better fit with the long-term vision for the server. + + Once you've got the go ahead, read through the coding standards document: + + https://wiki.freeradius.org/contributing/coding-standards + + If you're creating a new module you may wish to read the module creation guide: + + https://wiki.freeradius.org/contributing/Modules3 + + You may also wish to utilise the doxygen site to review code documentation: + + http://doc.freeradius.org + + The doxygen site contains the complete reference of all API functions with doxygen headers, as well + as structs, and callback declarations. doc.freeradius.org is updated within one minute of each commit + to the master branch of the main freeradius-server repo. + + Finally, this file was written to be displayed automatically on the GitHub issue tracker, so + Git/GitHub knowledge is assumed. If you're wondering what the heck a pull-request is, this + document may be of some use: + + https://wiki.freeradius.org/contributing/GitHub + + +5.CONTINUOUS INTEGRATION TESTS + + If possible include test cases in your pull-requests. + + There are currently three test frameworks for different elements of the server: + + Unit tests - src/tests/unit/*.txt - Tests for conditions and protocol encoders/decoders. + Module tests - src/tests/modules/<module name> - Tests for module functionality. + Unlang tests - src/tests/unlang/<test series> - Tests for unlang keywords and functions. + + See README.* docs in the directories above for basic information on writing test cases. The easiest + way to write new tests is to use the existing tests as examples. + + Tests are run via a GitHub Actions workflow for each pull-request, and on every commit by a develope + with repository access. |