Branches and Tags on IgorExchange

Branches
Tags
Example project organization
Do I really need to use branches and tags?

Branches and tags created within the repository for a project must be named in a certain way in order to be allowed by the server. Requiring a specified naming scheme makes it possible to automatically determine the required Igor Pro version and the project version from the branch/tag.

As a reminder, branches are used for development versions of a project, and automatic releases created from branches are created as development snapshots. Tags are used for official release versions of a project, and once a tag is generated that tag and its contents should not be changed. This makes it possible to refer to an official release of a project (for example, Window Desktops version 1.0) and know exactly the state of the code for that release.

See Creating a release with Subversion for a clarification of official vs. development snapshot releases and for instructions describing how to create releases for projects on IgorExchange.

Branches

The naming scheme for branches is:
IGOR-X-YY--M
where X, YY, and M represent:

X: Major version of Igor Pro.
YY: Minor version of Igor Pro. Must be 2 digits.
M: Major version of project.

Note that there are two hyphens separating the Igor Pro version from the major version of the project.

For example, a branch named IGOR-6-01--1 indicates that:

This branch of the project requires at least Igor Pro version 6.01 or greater.
This branch represents development for major version 1 of the project.

Example project organization

As an example of how branches and tags might be used in a very active project, here is the directory structure within the repository of a hypothetical project. To make this example clearer, individual files have been omitted in the listings--only the directory structure is shown. The placeholder [files] represents the actual files that would be present in the repository.
/packages/widget1 /trunk [files] /branches /IGOR-5-07--1 [files] /IGOR-6-01--1 [files] /IGOR-6-01--2 [files] /IGOR-6-02--3 [files] /tags /IGOR-5-07--1-0 [files] /IGOR-6-01--1-1 [files] /IGOR-6-01--1-2 [files] /IGOR-6-01--1-3 [files] /IGOR-6-01--2-0 [files] /IGOR-6-02--3-0-beta [files]
You might be wondering why the directory structure is so complicated and why there are so many branches and tags. To explain why, it might help to think of what the structure looked like earlier in the life of the project.

In the beginning, the project started out simple with just the basic /trunk, /branches, /tags directory structure that is recommended for all projects. All of the project's files were in the /trunk directory. So overall, the project looked like this:
packages/widget1 /trunk [files] /branches /tags

After working on the project for a while, the developer started to read more about Subversion branches and tags and decided that using them would be a good idea. At the time, he was using Igor Pro version 5.07 for his development, so he created a IGOR-5-07--1 branch of his project to indicate that the project required at least Igor Pro version 5.07 and that the major version of the project was version 1. He continued to develop the project using the files that were now in the IGOR-5-07--1 branch directory. After some time, he decided that the code was good enough to call finished and he created a IGOR-5-07--1-0 tag. He then created an official release of the project based on this tag. This marked version 1.0 of the project and indicated that the project required Igor Pro 5.07 or greater. The directory structure of the project now looked like this:
packages/widget1 /trunk [files] /branches /IGOR-5-07--1 [files] /tags /IGOR-5-07--1-0 [files]
At about the same time, the developers at WaveMetrics had put the finishing touches on Igor Pro version 6. Eager to try the dozens of new statistics functions, the developer upgraded to Igor Pro 6 right away. Thankfully, he also realized that he was about to add features to his project that required Igor 6, so he made a new IGOR-6-01--1 branch of his project based on the IGOR-5-07--1 branch. He then quickly added a few new features and created a IGOR-6-01--1-1 tag and an official released based on this tag. This indicated that version 1.1 of his project required Igor Pro version 6.01. The directory structure of the project now looked like this:
packages/widget1 /trunk [files] /branches /IGOR-5-07--1 [files] /IGOR-6-01--1 [files] /tags /IGOR-5-07--1-0 [files] /IGOR-6-01--1-1 [files]
After brainstorming for some time, the developer came up with a much better way to store and load one of the data files that his project handles. However, he wanted to give his users a bit of time to transition to the new file format. In order to handle this, he created a new branch based on the IGOR-6-01--1 branch. The new branch was called IGOR-6-01--2 to indicate that the new major version was 2 but that Igor Pro 6.01 was still required. After developing and testing the new file handling code, he created a tag called IGOR-6-01--2-0 and an official release based on that tag. The directory structure now appeared as
packages/widget1 /trunk [files] /branches /IGOR-5-07--1 [files] /IGOR-6-01--1 [files] /IGOR-6-01--2 [files] /tags /IGOR-5-07--1-0 [files] /IGOR-6-01--1-1 [files] /IGOR-6-01--2-0 [files]

He continued to make changes to files in the IGOR-6-01--1 branch when ever long standing bugs would be noticed, and occasionally created a new tag that included the changes made up to that point. Since these changes were minor, he decided to increase only the minor version number instead of changing the major version number. So, over time, he ended up with IGOR-6-01--1-2 and IGOR-6-01--1-3 tags. These two tags were created from the IGOR-6-01--1 branch and thus did not have the new file handling code. At this point, the directory structure looked like this:
packages/widget1 /trunk [files] /branches /IGOR-5-07--1 [files] /IGOR-6-01--1 [files] /IGOR-6-01--2 [files] /tags /IGOR-5-07--1-0 [files] /IGOR-6-01--1-1 [files] /IGOR-6-01--1-2 [files] /IGOR-6-01--1-3 [files] /IGOR-6-01--2-0 [files]
Finally, Igor Pro 6.02 was released with even more handy features. The developer first created a IGOR-6-02--3 branch based on the IGOR-6-01--2 branch and started adding new features. Eventually the developer created a IGOR-6-02--3-0-beta tag and an official release based on that tag. This indicated that the project requires Igor Pro version 6.02 and that the project's version was 3.0 (and that it was a beta version). Finally, the directory structure looks like it does in the example at the top of this section.

Do I really need to use branches and tags?

Some users may wonder if they really need to go to the trouble of using branches and tags or if they can just do all of their development on a project in the /trunk directory. The simple answer is no--branches and tags aren't required, and one can get by without using them. However, if you chose to not use branches and tags, there are some pitfalls that you might run across:

While you can create a release from the /trunk directory, you can only create one release from the trunk, and the packaging scripts will automatically recreate this release each time you commit a change to the repository. If you don't thoroughly test each change you make to the code before you commit the change to the repository, users may end up downloading code in a packaged release that is buggy.
In a similar way, if you add new features to your project that require a newer version of Igor Pro, users of your project who do not have that newest version will no longer be able to use your project, since it's only possible to create one downloadable release based on the /trunk of your project.

User-to-user support and collaboration