Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Small grammar tweak

...

Section
Column
Panel
titlePrevious Wording

New features are only accepted in trunk. New features should not be added to release branches, unless first approved by the branch maintainers (this is highly unlikely, unless the new feature exists solely in a stand alone module).

Note
titleAsterisk 12 is Different

Due to the scope of Asterisk 12, the project will be altering the "no new features in release branches" policy for this version only. This does not apply to any other release branch of Asterisk.

Improvements and new features that are related to the goals of Asterisk 12 will be allowed throughout the maintenance lifetime of Asterisk 12, subject to the following constraints:

  1. The new feature or improvement must be made in relation to the goals of Asterisk 12; namely, the improvement or new feature must be in one of the following areas:
    1. The new SIP stack based on PJSIP
    2. The core APIs facilitating the new external APIs, that is, the Bridging API and the Stasis Message Bus
    3. External facing APIs (AMI, ARI, AGI)
  2. The new feature or improvement must have thorough unit testing and/or functional testing provided by the Asterisk Test Suite. No new features or improvements without test coverage will be allowed midstream.
  3. Any new feature or improvement must go through the normal Asterisk new feature process. This includes a thorough code review on Review Board. If you have questions about whether or not the new feature or improvement will be accepted or is appropriate, please ask in #asterisk-dev or the asterisk-dev mailing list before development.

Any new feature applied to Asterisk 12 will also be applied to Asterisk trunk. New features that do not meet the criteria outlined above are still valid candidates for inclusion in Asterisk trunk and will be available in the next release of Asterisk (Asterisk 13), which will be an LTS release.

 

Info

Why are new features not allowed in release branches? We debate this policy often, but the reasoning goes:

  • New features require significant testing efforts that are better handled through the yearly beta process.
  • New features run a greater risk of perturbing the existing code base, making the risk of injecting negative effects into production systems greater.
  • New features create a 'moving target' for system administrators and system integrators, making upgrades for bug fixes difficult and costly.
Column
Panel
titleNew Wording

New features must always be written against trunk first. A new feature may be proposed for an existing release branch, subject to the following conditions:

  • Any new feature proposed for an existing release branch must have suitable test coverage using either the Asterisk Test Suite, the Asterisk Unit Test Framework, or both.

    Tip

    Tests are always good and encouraged, especially for new features. Having tests is a mandatory requirement for new features in release branches to minimize the risk of regression.

  • The new feature or improvement must be backwards compatible with the previous releases in those major versions. That is, users upgrading from one point release to the next should not be aware of any new feature or improvement unless they want to use said feature. Some things that should not be changed naturally follow from this:
    • APIs that follow semantic versioning should not receive a major version increase.
    • Configuration and database schemas can be added to or updated, but users should not be required to update their configuration or databases.
  • Any new features or improvements must be included in the first release candidate of a new version. First release candidate announcements must be made to the asterisk-users mailing lists, with at least a week of testing time allowed. If a new feature or improvement is deemed to cause an inappropriate burden on end-users, it must be removed from the release.

Generally, new features or improvements should always be done as new modules where possible, and those modules should be disabled if included in a release branch. If changes are necessary to the Asterisk core, all care possible should be given to not impact existing modules.

...