summaryrefslogtreecommitdiffstats
path: root/CONTRIBUTING
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--CONTRIBUTING109
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.