Using GIT

Why Git?

The FreePBX project moved from Subversion to GIT in 2012 to make it easier to administer the modular architecture of the system. Separate GIT repositories (“repos”) for each module allowed for better tracking of changes on a per-module basis. GIT also made it easier to do distributed development on different devices that are sometimes disconnected from the network.

What is the Point of FreePBX on GitHub?

The FreePBX project was mirrored from internal GIT over to GitHub for several years after the move to GIT. Then, in late 2023, FreePBX moved primary open source development, issue tracking and security reporting over to GitHub. The Asterisk developers spelled out some great reasons why they made the move to GitHub and you can read about “The Great Asterisk Migration: A Year Later” on the Asterisk blog.

How can I help contribute code to FreePBX on GitHub?

The generic process for contributing open source code to FreePBX via GitHub with minimal separate tools that are commonly found on GNU/Linux systems might look as follows:

1. First, in your web browser, open an issue by clicking on the “New Issue” button in the FreePBX issue-tracker repository.

   1. You may need to sign-in or set-up to GitHub if you don’t already have an account there.

   2. TIP: Try your email address with a positive twist eg. me+github@example.com to help limit spam.

2. Use the appropriate issue template eg. Bug Fix, Improvement, etc., and in the issue notes, identify the problem that you want to solve.

   1. Click the “Submit New Issue” button at the bottom to make it go public.

   2. GitHub will automatically generate a new issue number eg. XYZ - keep track of it - this will help you to reference it in the next few steps.

3. Navigate to the repository of the specific FreePBX module you are patching, and use the “Fork” button to fork a copy into your own account with a name like “freepbx-MODULENAME”.

   1. You can choose to fork from the default of only the main upstream branch - that should be fine in most cases.

   2. Forking the whole tree with all the branches will probably take more time.

4. Make a new branch in your fork with the name of the issue at the end eg. “clean-example-issue-XYZ” (replacing XYZ with your issue number from Step 2.)

5. Open up a shell terminal (or IDE) for the next few steps…

   1. Make sure you have ssh and git installed.

      1. Installing ssh-keys to your GitHub account will make things even easier.

      2. Using separate (virtual) machines for testing and development can be a lot of fun, too!

   2. Navigate to a new/reasonable directory for your work eg.

      1. mkdir ~/freepbx-code

      2. cd ~/freepbx-code

   3. Clone the repo you named in Step 3 and checkout your new branch you named in Step 4 eg.

      1. git clone git@example.com:USERNAME/freepbx-MODULENAME.git

         1. Replace “example.com” with “github.com”.

         2. Replace “USERNAME” with your username.

         3. Replace “MODULENAME” with the module name from Step 3.

      2. cd freepbx-MODULENAME

         1. Replace “MODULENAME” with the module name from Step 3.

      3. git checkout clean-example-issue-XYZ

         1. Replace “clean-example-issue-XYZ” with the branch name from Step 4.

6. Fix the issue and test, test, test.

7. Run git diff to review your changes.

8. Run git add . to prepare/group all of your changes.

9. Run git commit to type up a message describing your changes.

   1. Either nano or vim will usually pop-up, depending on your git editor preferences.

   2. Brevity good. But sometimes details are necessary to precisely capture the significance of the moment that things changed as time moved on.

   3. You might consider starting the message with the name of the module(s) affected eg.

      1. "MODULENAME: Fix the issue where ...”

   4. Include a line after your message to cross-reference the issue from Step 2. eg.

      1. Bugfix FreePBX/issue-tracker#XYZ

      2. ^^^ this format will automatically generate bidirectional hyperlinks: from issue to patch and vice-versa (even across repos - making it easier for code reviews of merges - neat!)

   5. Save the commit message using normal nano/vim methods.

10. Run git push to make your changes “public” in this branch of your forked repo.

11. Back in your web browser, navigate to your fork in your repo, and then a button should appear near the top, asking if you want to submit a Pull Request. Double-check your work and the branch names and make it so!

12. Finally, in your browser, navigate to your issue in the issue-tracker, and take a look at the log to confirm it cross-referenced your patch. You may need to accept the Contributor License Agreement as well.

The above steps go well together with https://sangomakb.atlassian.net/wiki/x/AoBLEg