Skip to end of metadata
Go to start of metadata

Historical Page

Icon

The Asterisk project no longer uses Subversion for source control. It now uses Git. Instructions on using Git with Asterisk can be on the Git Usage page.

This page is being kept only for historical purposes.

1. Commit Access

1.1. Configuration

The subversion server uses SSL client certificates to handle authentication of users. When you are granted commit access, you will be provided two files. These files should be placed in your ~/.subversion/ directory.

  1. Digium_SVN-cacert-sha1.pem
  2. <name>-cert.p12

The following should be placed in the ~/.subversion/servers file:

~/.subversion/servers

1.2. SVN Checkouts

Checkouts that come from http://svn.asterisk.org/ are read-only copies of the repositories. When doing a checkout that you intend to commit to, it must be from https://origsvn.digium.com/. For example:

2. Using svnmerge for Cross-Branch Merging

2.1. Tools Installation

You must install svnmerge and the related wrappers from our repotools repository. The wrapper scripts use expect, so be sure to install that, too.

2.2. svnmerge Properties

If you do a svn pl -v while you are located in an svn checkout, you will see all the properties currently attached to the root directory. For instance, on a checked out copy of Asterisk trunk, you will see something like this:

  branch-1.8-blocked
    /branches/1.8:
  branch-1.8-merged
    /branches/1.8:1-279056,279113,279227,279273,279280,...............,286457

and on the 1.8 branch, you will see these sort of properties:

  branch-1.6.2-blocked
    /branches/1.6.2:279852,279883,280227,280556,280812,282668
  branch-1.6.2-merged
    /branches/1.6.2:1-279056,279207,279501,279561,279597,279609,....................,286268

These properties identify the following things:

  1. The branch changes are being merged from
    • branch-<branch>-...
  2. The revisions merged from that branch
    • branch-<branch>-merged:/branches/<branch>:<revisions>
  3. The revision explicitly not merged, or blocked, from that branch
    • branch-<branch>-blocked:/branches/<branch>:<revisions>

2.3. Branch Merging Order

When committing a change that applies to more than one branch, the change should first go into the oldest branch and will then be merged up to the next one. If a branch is reached where the change should not be merged up, it should be explicitly blocked. The following diagram shows the current branch merge order.

The column on the right describes the scripts you will use to merge between versions or block specific versions from merging.

  • 1.8 -> 11
    • merge811 <revision>
    • block811 <revision>
  • 11 -> 12
    • merge1112 <revision>
    • block1112 <revision>
  • 12 -> 13
    • merge1213 <revision>
    • block1213 <revision>
  • 13 -> trunk
    • merge13trunk <revision>
    • block13trunk <revision>

The <revision> number passed to each script should be the revision resulting from the commit to an older branch. The script would be run from the checkout directory for the Asterisk version you are merging to.

For example if you have committed a change to 13 and that needs to be merged through to trunk, the commands would look similar to the following:

/svn-asterisk-13$ svn commit -F ../commit_msg
Sending        apps/app_voicemail.c
Transmitting file data .
Committed revision 376262.
/svn-asterisk-13$ cd ../svn-asterisk-trunk
/svn-asterisk-trunk$ merge13trunk 376262

Then you would proceed with committing the merged changes.

Icon

All of these scripts create a commit message for you in the file ../merge.msg. Run "svn commit" and use that commit message with the following command:

Icon

Sometimes when you go to commit your changes after merging from another branch, you will end up with a conflict. The conflict will typically be against . (period). To resolve the conflict, run "svn resolved ." prior to committing.

2.4. Backporting Changes

Sometimes a change is made in a branch and later it is decided that it should be backported to an older branch. For example, a change may have gone into the 11 branch and later needs to be backported to the 1.8 branch. To handle this, first manually make the change and commit to the 1.8 branch. Then, there is another wrapper similar to merge811 and block811 to record that the code from a revision already exists in the 11 branch. The wrapper is record811.

3. Developer Branches

Icon

If you have been granted workspace on the server, you will have read and electronically signed the Open Source Contributor License found at https://issues.asterisk.org (upon signing in) and have been given an SSL client certificate.

Developer branches are stored in the /team/<name> directory of each project repository (and /team/<name>/private for private branches).

3.1. Creating a Developer Branch

Use the following commands to create a branch and prepare it for future merge tracking of the branch you created it from. This example creates a branch off of Asterisk trunk.

3.2. Deleting a Developer Branch

To delete a developer branch after you are done with it use the SVN command shown below for your branch name.

3.3. Group Branches

Group branches are developer branches intended to be worked on by more than one developer. Instead of putting them in /team/<name>, they go in the /team/group directory, instead. Otherwise, they're managed in the exact same way as other developer branches.

3.4. Automatically Keeping Branches Up to Date Using automerge

Our subversion server provides the ability to automatically keep developer branches up to date with their parent. To enable this feature, set the automerge and automerge-email properties on the root directory. Changes from the parent branch will be periodically (once an hour) merged into your branch. If a change from upstream conflicts with changes in the branch, the automerge process will stop and the address(es) listed in the automerge-email property will be notified.

Icon

Running svnmerge init and committing those properties is a prerequisite for automerge to work for a developer branch.

Use the following commands to enable automerge on a developer branch:

3.4.1. Setting automerge-email on a Group Branch

For a branch with multiple developers working on it, it may be useful to have automerge emails sent to more than one email address. To do so, just separate the email addresses in the property with commas. The value of this property is literally used as the content for the To: header of the email.

3.4.2. Resolving automerge Conflicts

If your developer branch goes into conflict with automerge on, and the automerge-email property has been set, you will receive an email notifying you of the conflict and automerge will be disabled. To resolve it, use the following commands:

Running the svnmerge tool will merge in the changes that cause your branch to go into conflict into your local copy. Edit the files that are in conflict to resolve the problems as appropriate. Finally, tell SVN that you have resolved the problem, re-enable automerge, and commit.

3.5. Private Branches

A private developer branch is only visible to Digium and the branch owner. Management of a private branch is exactly the same as any other developer branch. The only difference is branch location. Instead of putting the branch in /team/<name>/ the branch goes in /team/<name>/private/.

3.6. Merging a Developer Branch into trunk

Icon

If your branch contains new functionality, please make sure you have made the appropriate modifications to CHANGES and/or UPGRADE.txt.

If a developer has a branch that is ready to be merged back into the trunk, here is the process:

Be sure to check the resulting diff to make sure that the merge doesn't overwrite any changes in trunk. If it does, you will have to specify the specific revisions merge needs to base its diff off of.

Icon

This is NOT using the svnmerge script; this is just a normal SVN merge.

Once this is done, the working copy will contain the trunk plus the changes from the developer branch. If you follow the above instructions for creating branches, you have probably introduced properties to the root of the branch that need to be removed.

If you are purposely introducing new properties, or purposely introducing new values for existing properties, then you might do the following instead, so as not to destroy your properties:

If everything merged cleanly, you can test compile and then:

Once the contents of your branch has been merged, please use svn remove to remove it from the repository. It will still be accessible if needed by looking back in the repository history if needed.

  • No labels

12 Comments

    1. I suggest we add a Prerequisites section

      Icon

      Ensure you always have the most recent version of svnmerge from the repotools repository.

      We can then update the Makefile for repotool to install Digium_SVN-cacert-sha1.pem to the proper location.

      1. I like this idea. I would also show an SVN checkout directly to the install location so that it is more transparent to the user in documentation.

        Tested example...

        wget http://svn.asterisk.org/svn/repotools/Digium_SVN-cacert-sha1.pem -O ~/.subversion/Digium_SVN-cacert-sha1.pem

        • BTW: I am a longtime Mediawiki user, where is the preview button on this wiki...
  1. Add ./configure to 2.1. Tools Installation for repotools

  2. Start documenting the merge information... I read this page and others multiple times and it took some hunting to find that the commands are actually merge and are links to svnmerge (repotools version). I love it when a verb in a command name becomes confusing...

    merge24, merge46, merge68, merge8trunk, mergedevtrunk -> /usr/local/bin/svnmerge

    and

    block24, block46, block68, block8trunk, blockdevtrunk -> /usr/local/bin/svnmerge

    1. You might be interested in: https://issues.asterisk.org/file_download.php?file_id=26898&type=bug

      I'm sure we could import some of it into the wiki.

      1. Thank you, I found http://www.asterisk.org/node/121 also. I think the overall issue was stress, I could not see the forest though the trees.

  3. In some magical way the properties of my development checkouts got messed up. I saved the directories away and did fresh checkouts to get my work done. I did not do any advanced svn changes. Can we document some common ways that the properties would get out of sync?

    I have my bad directories saved if anyone wants to look at them.

  4. Note: Add a section on adding and removing files. Setting properties and mime types.

  5. I was just reading and went to look at record810 which is not installed from repotools or I am blind, one of the two...

    1. Its part of mergetool, which wraps around svnmerge. Example:

      1. It was there the whole time, I was typing report and hitting tab... I put down the laptop for a few hours, thanks. (big grin)