Before You Begin...
Before writing a new feature for Asterisk, there are multiple things to consider.
- Is the feature general purpose enough that it is appropriate for all Asterisk consumers?
- Is the feature appropriate for the next major version release?
- How can I help reviewers of the feature verify its correctness?
- How can I help Asterisk developers maintain the new feature, once it is included?
Is a New Feature Appropriate?
Whether or not a new feature is appropriate for inclusion in Asterisk is a tricky question. If you're considering adding a new feature to Asterisk, you obviously find it useful! However, not everyone uses Asterisk the same way, and features added to Asterisk should be as generally applicable to everyone as possible.
Some questions you should ask yourself when thinking about whether or not your feature is appropriate in Asterisk:
- Does the new feature contain logic that is specific to an Asterisk deployment scenario?
- Can the new feature be implemented using Asterisk interfaces and without modifying the Asterisk source?
- Does the new feature change long standing Asterisk conventions?
If the answer is No to all of the above questions, then the feature may be appropriate for Asterisk. A Yes to any of the above questions does not invalidate the new feature, but it may mean that discussion on the asterisk-dev mailing list is appropriate before submitting the patch to the issue tracker. If in peer review, you may be asked to change the feature to make it more suitable.
Some case studies illustrating features that could be considered for inclusion in Asterisk and why or why not they are appropriate are below.
Is the Feature Appropriate for the next Major Version?
Each year, the Asterisk trunk is made into a major version branch. Periodically, releases are made from the major version branches. There are two types of major version branches, Standard and Long Term Support (LTS). The two types differ both in their supported lifetimes as well as their development focus.
If a new feature changes the architecture of Asterisk or has a particularly large impact on core functionality, the preference is to have that new feature released in a Standard release. LTS releases should include new features that enhance the Asterisk experience, but should avoid major internal changes that fundamentally alter behavior.
Some examples are listed below. Note that Standard releases can include any new feature, and hence new features that are appropriate for an LTS release are technically appropriate for any Asterisk release.
Not only did this change add new functionality, but it had a ripple effect throughout the code base requiring all consumers/producers of media to change. Due to its large scope, it was more appropriate for a Standard release.
While hangup handlers did require some changes in the Asterisk core, they were limited in scope and were easy to define - that is, we had to concern ourselves with locations where the 'h' extension would be executed, but the behavior of the 'h' extension was not altered.
On its face, T.38 gateway appears to be a feature that is relatively non-intrusive, as much of its handling exists in a separate resource module (res_fax). However, in order to enable/disable gateway mode, chan_sip had to be able to maintain some rather complicated state information. This was relatively tricky, as chan_sip does not have a modular design and does not lend itself well to code changes. It was best handled in a Standard release; if chan_sip was more flexible, then this could potentially have been done in an LTS release.
While Unique Call ID Logging affected a large number of modules (channel drivers + the logging core, as well as other core modules), the changes were relatively small and unintrusive. In addition, if a module chose not to make use of the Unique Call IDs for log messages, it still behaved exactly the same. The fact that the behavior is optional is what makes this easy to justify in an LTS release.
If your feature is deemed to be intrusive or risky for an LTS release and you are asked to hold off on including it, a branch can be set up to maintain the feature in parallel with the current Asterisk trunk using automerge. See Subversion Usage for more information.
Is the Feature Correct?
There are many ways of testing a new feature. The simplest, and most common, is the 'developer test', where the developer of a new feature verifies that it works on their development machine. While this is good, as the complexity of a new feature increases, the more difficult it becomes to verify that the new feature (a) works as intended and (b) does not adversely impact other Asterisk features.
Testing your new feature is extremely beneficial to those who have to review, approve, and maintain your feature. See Testing for more information.
Is the Feature Maintainable?
Maintainability is a tricky proposition. When a developer writes a new feature, the implementation makes perfect sense! However, not all developers view code the same way, and even the same developer - upon revisiting code at a later date - may forget why something was implemented the way it was. These problems are compounded by code complexity, differences in coding standards, and poorly abstracted design.
Making your new feature maintainable goes a long way to getting it included in Asterisk. Features that fit well within the Asterisk architecture; are easy to inspect and test; and impact as little existing code as possible are much easier to incorporate than features that are not well compartmentalized. The following are a list of questions to ask yourself when you're writing your new feature that will help in making the feature maintainable:
- Are you following the established Asterisk coding guidelines?
- Are you using all of the appropriate Asterisk libraries, and are you using them for their intended purpose?
- Have you thought about how your code will be tested?
- Can the new feature exist in a separate module?
- Are the places where the new feature interacts with existing code well understood? By that, think about:
- Do you need to refactor any existing code to make the new feature easier to understand and verify?
New Feature Development
New features are developed against Asterisk trunk. You may propose that a feature be included in a release branch as well, if the feature is appropriate for the type of release branch. New features included in a release branch must have accompanying automated tests. See Software Configuration Management Policies for more information about the various branches in Asterisk.
New features and improvements can have an issue in JIRA, if there is a developer who is assigned and working the issue. Once the new feature or improvement has been made, a patch should be made and placed on the issue.
Note that you must sign a Digium License Agreement to contribute any code back to the Asterisk project.
It is generally recommended that developers for major new features create a page on the wiki using the Project Planning Template under the Roadmap section's page for the next major Asterisk version. Even before implementation of a new feature begins, basic requirements and design can be documented and discussed.
When starting a major new feature, an e-mail should be sent to the Asterisk Developer's Mailing List announcing the development of the feature. This announcement can also be used to discuss whether or not the feature is appropriate for inclusion in Asterisk. If you feature impacts an Asterisk interface, you may also consider announcing the development of the feature on the Asterisk Application Development mailing list.
Periodically, it is recommended that the primary developer for a new feature send updates to the Asterisk Developer Mailing List updating the community with the status of the project.
All new features should have automated tests. New features that are proposed for an existing release branch must have accompanying tests.
New features with a project plan on the wiki can document their test plans, which is useful both in the outlining of the new feature as well as to gain help on testing a feature. Each major requirement of a new feature should have some level of test coverage to help verify its functionality. Tests that exist at the Unit or Integration level may use the Asterisk Unit Test Framework or Asterisk Test Suite, respectively.
The Asterisk project provides a number of ways to help you test your feature:
- Unit tests, using the Asterisk Unit Test Framework.
- Functional/Integration tests, using the Asterisk Test Suite.
- Beta testing with the Asterisk community, conducted as part of a major version release cycle. Note that all major versions go through a beta test cycle.
Making use of the Unit Test Framework and the Asterisk Test Suite is highly encouraged for all new features. Tests written for either framework are automatically included in the Asterisk project's continuous integration activities. This helps not only to verify the correctness of the new feature, but also make it maintainable (see the next section).
Individual tests at any level are not guaranteed to catch all bugs. The types of bugs caught in Unit or Integration tests often differ greatly from the types of tests caught in System or Beta tests. Taken as a whole, testing at all layers builds a safety net that guarantees that new features provide the basic functionality that they promise, as well as not impact other areas of the code base.
Implementation is left up to the developers working on the new feature. The project does provide several resources to collaborate on a new feature:
- The asterisk-dev mailing list can and should be used for any and all discussions about code
- The #asterisk-dev IRC channel on freenode
- The Asterisk wiki contains substantial information in the Development section. In particular, be mindful of the Coding Guidelines.
- For developers with commit access, team branches can be used to help keep a new feature in sync with particular branches. See Subversion Usage for more information about team branches.
When implementation is complete, patches should be attached to the JIRA issues and the new feature put up for Code Review. Be sure to read the Coding Guidelines, as well as the Code Review Checklist prior to putting the patch up for review.
The following resources exist to help you when writing a new feature for Asterisk. Your best resource, however, are other Asterisk Developers. Never hesitate to use the mailing lists and IRC channels to discuss a feature or an issue you may be facing.
- Project Planning Template - used for describing a new feature and coordinating plans.
- Roadmap - major goals for Asterisk versions, and descriptions of new features and improvements being proposed and worked on for the next major version.
- Open Features and Improvements - current new features and improvements open in the issue tracker, but not yet committed to SVN.
- Issue Tracker Workflow - how issues are moved through the public Asterisk project.
- Code Review - how code reviews are performed. This contains links to lots of other useful information, including:
- Gerrit Usage - How to use Gerrit for code reviews.
- Coding Guidelines - Follow these for all C code. For Python code, use PEP8. For other code, try to match the project you are working in.
- Code Review Checklist - useful things to keep in mind when reviewing code (and before putting your code up for review)
- Commit Messages - how to write proper commit messages.
- Git Usage - information on the available Git repositories.
- Repotools - useful tools that are needed for the Asterisk SVN repositories.
- code.asterisk.org - Fisheye/Crucible. Slow (due to the size and history of the project), but effective at getting SVN history/stats.
- doxygen.asterisk.org - auto-generated doxygen information from Asterisk trunk.