-= Submitting patches via GitHub
+= Submitting Patches via GitHub
== Introduction
GitHub is a social coding site allowing many developers to come together and work on projects simultaneously.
-GitHub is based on the Git version control system. What makes Git different from other version control systems (like CVS and SVN), is that there is no need for a central master repository. When you *clone* (checkout) a repository, you get your own private repository containing all the commits and branches of the original.
+GitHub is based on the Git version control system. What makes Git different from other version control systems (like CVS and SVN), is that there is no need for a central master repository. When you *clone* (checkout) a repository, you get your own private repository containing all the commits and branches of the original.
After cloning a repository you can create new branches and commit new revisions completely independently of the *upstream* repository. To distribute and receive changes you can use the `git pull` command (to get new commits from remote repositories), and `git push` command (to send your commits to remote repositories).
In order to follow or fork a project you must first create a GitHub account. The current signup url is https://github.com/signup/free and the process is pretty straight forward. After you've signed up, log in and you're good to go.
-Another advantage of having a GitHub account is its one of the providers this wiki supports for login, so even if you never contribute to the source code of the server, you'll still be able to help out be adding wiki content.
+Another advantage of having a GitHub account is its one of the providers this wiki supports for login, so even if you never contribute to the source code of the server, you'll still be able to help out be adding wiki content.
== Authorising your local machine to talk to GitHub
* Login to GitHub
* Go to the [[project site|https://github.com/FreeRADIUS/freeradius-server]]
-* Click the 'Fork' button.
+* Click the 'Fork' button.
You'll see the current URL change to ``/<your github username>/freeradius-server`` this means you're now browsing your own copy of the FreeRADIUS source code. From this point on changes to the *upstream* repository will not be reflected in your fork, unless you explicitly pull from the *upstream* repository using the local clone of your fork, and push back to GitHub.
Before you start hacking away you must create a new branch. This branch will serve to group your commits together so that they can be merged back to the project repository later.
-==== Branching
+==== Branching
* Think of a descriptive name for your branch, something like 'rlm_foo_segfault_issues'
* Navigate to your local git repo:
----
git checkout <my new branch>
----
-
+
==== Commits and pushing changes
* Hack away at the server code or apply a pre-existing patch or set of diffs
* Pull from upstream to make sure there are no conflicts, and to merge the latest commits from the project repository:
----
-git pull --rebase upstream <development branch>
+git pull --rebase upstream <development branch>
----
* Push changes back to your fork:
----
git push
-----
+----
See http://doc.freeradius.org for the current development branch
==== Rebasing
-Another rather unique feature of Git is the concept of rebasing. Rebase allows you to rewind the state of your repository to an earlier revision, then re-apply ranges of commits.
+Another rather unique feature of Git is the concept of rebasing. Rebase allows you to rewind the state of your repository to an earlier revision, then re-apply ranges of commits.
In the section above the `git pull --rebase` command is used, heres what that command actually does
If your code merges cleanly, then its a couple of clicks to get it merged into the project repository. This is **significantly** easier for core developers, compared with applying mangled patches sent on the mailing lists.
* Go to your fork on GitHub `https://github.com/<your github username>/freeradius-server`
-* Click the 'Pull request' button
+* Click the 'Pull request' button
* Follow the instructions...
==== Signing commits
= FreeRADIUS Development
-List with some usual howtos for FreeRADIUS.
+As the name suggests, FreeRADIUS is developed under the GNU General Public License, Version 2 (GPLv2). We invite anyone to use and contribute code to the project. The following information should be helpful to those who want to contribute.
-Programming reference documentation can be found at the
-https://doc.freeradius.org/[Doxygen] site.
+The official FreeRADIUS v4 developer guidelines are also online at the https://www.freeradius.org/documentation/freeradius-server/4.0.0[project's website].
-## Instructions for Developers
+Key resources for developers include:
-As the name suggests, FreeRADIUS is developed under the GNU
-General Public License, Version 2 (GPLv2).
-We invite anyone to use and contribute code to the project. The
-following information should prove useful for potential
-contributors.
+* Developers Section: This part of the official documentation covers topics like bug reporting, coding methods, module interfaces, and buffer handling.
-## Patches and contributions
+* Module Interface Documentation: This resource explains how to develop modules for the FreeRADIUS server.
-Development of FreeRADIUS is done using
-Github. Please
-submit issues, bugs, patches, etc. there. Additional instructions are on
-the wiki.
+* GitHub Repository: The source code and all documentation files are on GitHub, giving developers access to the latest information and a way to contribute.
-## Development mailing list
-
-We encourage everyone who might contribute code to join the FreeRADIUS
-development list(http://www.freeradius.org/list/devel.html). This
-list is highly technical and isn't for most users of the server.
-For normal discussion of the server and how to use it, subscribe to the
-https://lists.freeradius.org/mailman/listinfo/freeradius-users[FreeRADIUS user-list].
-*Only* subscribe to the development list if you are
+* Development mailing list: We encourage everyone who might contribute code to join the http://www.freeradius.org/list/devel.html[FreeRADIUS
+development list]. This list is highly technical and isn't for most users of the server. *Only* subscribe to the development list if you are
interested in writing software for the new server.
+For normal discussion of the server and how to use it, subscribe to the https://lists.freeradius.org/mailman/listinfo/freeradius-users[FreeRADIUS user-list].
+
+== xref:bugs.adoc[Bugs]
+
+If the server crashes due to memory errors, report it to the issue tracker with debugging info. For other issues, discuss them on the users mailing list.
+
+== xref:coding-methods.adoc[Coding Methods]
+
+This is a short set of guidelines to follow when programming. Coding standards focus on function names, code appearance, and consistency.
+
+== xref:coverage.adoc[Code Coverage]
+
+The gcov tool analyzes your programs. It helps you create efficient code and find untested areas.
+
+== xref:profile.adoc[Profiling]
+
+The gperftools (Google Performance Tools) help you find memory leaks, analyze performance issues, and optimize your code.
+
+== xref:coccinelle.adoc[Semantic Patches]
+
+Coccinelle analyzes and transforms C code to create Semantic Patch Language (SmPL) patches.
+
+== xref:contributing.adoc[Contributing]
+
+Development of FreeRADIUS is done using Github. Please submit issues, bugs, patches, etc. there. Additional instructions are online or within this section.
+
+== xref:module_interface.adoc[Module Interface]
+
+The purpose of modules is to handle small, simple tasks when RADIUS packets arrive. The module framework is built to process incoming RADIUS packets. It is also highly customizable.
+
+== xref:release-method.adoc[Release Method]
+
+Review the steps to push or update a release.
+
+== xref:buffers.adoc[Buffer Management]
+FreeRADIUS provides APIs to handle xref:dbuff.adoc[Data] and
+xref:sbuff.adoc[String] buffers enabling devlopers to streamline their coding and processes.
-## Miscellaneous links
+== More Information
-RADIUS RFC's and drafts: The two
-most important are
-RFC2865(http://www.freeradius.org/rfc/rfc2865.html) and
-RFC2866.(http://www.freeradius.org/rfc/rfc2866.html). These are
+The two most important RADIUS RFC's and drafts are
+http://www.freeradius.org/rfc/rfc2865.html[RFC2865] and
+http://www.freeradius.org/rfc/rfc2866.html[RFC2866]. These are
the new RFCs, which replace the old ones,
-RFC2138(http://www.freeradius.org/rfc/rfc2138.txt) and
-RFC2139(http://www.freeradius.org/rfc/rfc2139.txt)
-
-== Topics
-
-* xref:bugs.adoc[Bugs]
-* xref:coding-methods.adoc[Coding Methods]
-* xref:coverage.adoc[Code Coverage]
-* xref:profile.adoc[Profiling]
-* xref:coccinelle.adoc[Semantic Patches]
-* xref:contributing.adoc[Contributing]
-* xref:module_interface.adoc[Module Interface]
-* xref:release-method.adoc[Release Method]
-* Buffer handling
-** xref:dbuff.adoc[Data buffers] (`dbuff` s)
-** xref:sbuff.adoc[String buffers] (`sbuff` s)
-** xref:sbuff-parsing.adoc[Parsing with string buffers]
-** xref:sbuff-ng.adoc[Sbuff issues]
+http://www.freeradius.org/rfc/rfc2138.txt[RFC2138] and
+http://www.freeradius.org/rfc/rfc2139.txt[RFC2139].
Also see the xref:howto:installation/dependencies.adoc[build
dependencies] page.
projects / thirdparty / freeradius-server.git / commitdiff
