From Norganna's AddOns

Roles and Structure

Organization

The development team is divided up into several logical layers and roles, each of which may be viewed on the Organizational Chart. You may click on a role on the chart to see more detail for that role.

Tools and Processes

Editing code

What editors we use

We use a mixture of code editors here, from Notepad++, TextPad, UltraEdit (Warning: UltraEdit seems to come with some AdWare components when you install it), Vim, and XEmacs. Any UTF-8 capable text editor is acceptable and you are encouraged to use your own choice.

Coding Style

We use a simple coding style rules here.

UTF-8 formatted files (No BOM)
Tab indent.
4-space tabstops.
No semi-colon at instruction end.
No whitespace at line end.

Other than that, you are pretty much free to chose your own style of code.

SVN Access

About our Subversion repository

The public (read-only) SVN repository is at http://svn.norganna.org/ for most users this is the one they will use, or possibly they may prefer to do a once-off download of a developer zip (at http://zip.norganna.org/).

Developers however use the main SVN repository at http://dev.norganna.org/ which is read-write, requires a developer username and password to access and is the primary development repository that we use for our projects.

Applying for developer access

If you're a normal user, but you'd like to be an official developer, make sure you come and speak to someone on IRC. Even if you're not a coder, we would still love to talk to you about how you could help out in an official capacity.

SVN Configuration

Checking out the code

In order to utilize the developer SVN repository, you will need to install a Subversion client onto your computer. For Windows users, the easiest way to do this is to head over to http://tortoisesvn.net and get the Tortoise SVN client.

Once you have downloaded and installed the SVN client, you will need to checkout one or more of the following repository URLs. To do this, simply create a blank folder on your hard drive (this folder will be called your "Working Copy"), right click on the blank folder and select the new SVN Checkout... option.

The following URLs are known as the "trunk" of our development. It's where most of our work takes place, and these are the best versions for you to checkout:

Setting up your AddOns folder

You've now completed the checkout, and will now have the copies of the repository on your hard drive for you to work on. However at this stage they are not installed in your AddOns folder, and you can't play with them in the game.

To do this (if you have a Windows/NTFS filesystem) we recommend that you create junction points in your World of Warcraft\Interface\AddOns folder for each of the AddOn folders that you wish to play with. More info about junction point tools we can recommend (or at lease know about) can be found here.

Once you've installed and rebooted, go into your working copy directories, and select the folders you want to create junctions for in one Explorer window and follow the instructions for your particular tool to create a junction point for the folders into your Interface\AddOns folder opened in a second Explorer window - for many tools, this will involve right-click-and-dragging. Make sure the resulting folders weren't renamed to all start with "Link to..." - there should be an option in your tool of choice to prevent this if it does happen.

You should create junctions for most of the folders in the Auctioneer and/or Gatherer trunk folders and at least the Stubby, Configator and Babylonian libraries from the Libs trunk.

Note: A recent change to WoW now seems to cause all Windows junctions to be deleted whenever there is a new release patch (i.e. any time you have to agree to the EULA again when logging in after a maintenance day). You will have to recreate all your junctions at this point, or else when you log in you will notice that all your auctioneer addons are not loaded (and in fact, not even visible to WoW).

SVN Usage

Where to commit changes

In general, you will commit changes to the trunk of the repository. This is where all primary development is performed.

On occasion, if the proposed change is large or complex enough, or if we want to stage it for a future release, one of the project admins may create a branch for you, and ask you to code specific changes in that branch instead of in trunk. If the change gets approved, you will later be asked to merge the branch back into the trunk.

How to commit changes to the repository

The developer SVN is available for you to make commits and code changes to, however every commit requires that you place a JIRA issue number along with your commit message before it will accept your changes.

If the task that you are working on does not have an issue number, you may go and create a new issue in JIRA just before the commit, although this is considered bad form. You should instead try to create an issue before you start working, and claim it so that others do not start working on the same issue as you have just fixed, or worse still, you do not just finish working on an issue to find out that somebody else just beat you to the punch.

How to organize your changes

In general, you should try to make your changes atomic - i.e. resolving only one (JIRA) issue at a time. This helps make sure your SVN commits are concise, with clear reasoning, and easy for other developers to understand and follow. There may be times when you need to work on two different changes at the same time, to reduce code complexity or minimize re-work, but this should be an exception, not the rule. As stated by the Apache development team:

Commit logical changesets

When you commit a change to the repository, make sure your change reflects a single purpose: the fixing of a specific bug, 
the addition of a new feature, or some particular task. Your commit will create a new revision number which can forever be 
used as a "name" for the change. You can mention this revision number in bug databases, or use it as an argument to svn merge 
should you want to undo the change or port it to another branch.

For particularly complex issues/changes, you can commit in multiple, incremental, logical pieces, as long as each commit leaves the code in working state. Never commit code that leaves things in a broken or unusable state.

Typing up your commit message

The commit message format that we use here is as follows:

<Fixes, Implements, Starts, or Completes> [JIRA-Number(Abbreviation needs to be in all caps)] Simplified, non-technical description 

More detailed/multiline
commit message
goes here if needed.

For example:

Fixes [GATH-107] Added Northrend ores and herbs to SkillLevel table

Be available when you commit your code

We do ask that you join the IRC channel when you commit a change, so that we can talk to you about it if there are issues, and please don't commit-and-run. Leave enough time to fix any potential issues with your commit, or else wait until you have some more free time before committing your change.

Be considerate of other users, check your changes

Also, any commits you make should leave the repository in a working state to the best of your knowledge. Other people use the repository as the source for their WoW's AddOns, and if you break it, then they will be upset. So please try and keep it functional by testing before committing, or if you absolutely have to dry-code a change, ask someone in the IRC channel to update and check for you.

JIRA Access

About JIRA

We use an issue tracker here called JIRA and it is available at http://jira.norganna.org/.

The issue manager forms the core of our operations. It defines the bugs, new features, improvements and tasks that need to be completed. As explained above, all code check-ins must be made against a specific JIRA issue.

JIRA Usage

To access JIRA, you will use the same username and password as you use on the forums.

You as a developer are free to add new bugs, features, improvements and tasks as you see fit. In general, each JIRA should address a single bug, feature, enhancement, or improvement. If the issue is large enough, you can use it as a single "umbrella" issue, and create sub-tasks underneath it to track the specific sets of changes needed to be implemented in order to achieve the larger piece of functionality.

Try to avoid combining two separate issues in a single JIRA item, even if they are related. It is preferable to create separate JIRA items for each, and then optionally link them together if it is appropriate.

For new functionality, it is generally a good idea to check with the other developers if your changes meet the strategic direction of the project before you start coding. Oftentimes this discussion can take place in the JIRA itself, and will be part of the process of confirming the issue. Create the task and then ask the other developers for feedback on it if you aren't sure.

When you are finished coding and have completed your testing, you should "Resolve" the issue, listing the resolution reason (usually "Fixed"). After you have resolved the issue, another member of the team is required to check your commits and code and "Close" the issue. You should never close your own tickets.

Fisheye Access

About Fisheye

To view the repository and it's current condition, changes and history, we use a tool known as fisheye at http://fisheye.norganna.org.

The fisheye tool allows us to monitor the repositories and see what's going on, who's working on what and past history of all the files that exist in the repository. It also contains another tool called Crucible which is covered in the next section.

To access Fisheye, you will use the same username and password as you use on the forums. Due to an issue in Fisheye, you must enter your username totally in lowercase. If you try to use uppercase letters in your username, you will not be allowed to login.

About Crucible

Crucible is a Peer Code Review tool that we use to monitor and review committed code that we see so as to improve the coding style and efficiency of committed code.

As a general rule a report should be made for all commits by the person who is responsible for closing the issue. That person should review the code, and if it meets with their approval, may close the report and the associated issue. Reviewers can easily create a new review from either the Activity tab in Fisheye (which shows all commits to a project) or from the activity log in JIRA.

As a developer, if you have a specific reason for wanting your code reviewed either pre- or post-commit, you can create a review yourself and assign it to a specific reviewer. You may do this if you are working with unfamiliar code, or if there is a specific teammate who has extensive knowledge with either the code being changed or the technique being employed.

A Step-by-step process for making a change to our code

Now that you understand the tools we use, it's time to pull it all together. Here is a step-by-step guide showing how a change gets made to our repository.

Start with an issue in JIRA. Make sure it is unassigned, and assign it to yourself (or talk to the current assignee before you work on it). "Start Progress" on the issue to indicate that it is an issue you are actively looking into.
Make your code changes, commenting where appropriate. Be sure to follow the Programming Standards, especially with respect to local/global variables.
Test your changes on your local code.
Before committing your code, you should first run an SVN Update, to make sure no other developers have made other changes while you were working (particularly changes to the same files you are working on, or that will affect you in some way).
On occasion, another developer will have made changes to the same files you are changing, and SVN will not be able to merge the changes together. In this case, you will need to manually resolve any conflicts.
If there have been any changes to the code, you should now retest, even if those changes were not to the same files you were testing. Sometimes changes in one place can accidentally (or deliberately) affect code in other places. When in doubt, retest.
Once you have finished testing and believe the issue is fixed, you should "Stop Progress" on the issue in JIRA.
Now it is time to commit your changes to SVN. Be sure to follow the commit guidelines above.
If ^nbot is running, check the main #norganna channel to review the commit message. In particular, be on the lookout for messages about global pollution. These indicate that your code has probably accidentally introduced some new global variables. Unless you have a good reason to need them to be global, and can explain it to the project lead, you should go back and edit your code with the Programming Standards in mind, and change those globals into locals! Rinse and repeat the above steps until everything is satisfactory.
If you're not completely confident in your changes, or want to be extra cautious, you can ask in IRC for one of the other team members to update their code and test your changes as well.
If you want a specific team member to code review your changes, you can create a Crucible review yourself, and assign it to that person or persons. You can do this from Fisheye (or the Fisheye tab in JIRA) - there is a convenient link to "Create a new review" next to each SVN commit displayed in Fisheye. Otherwise, the QA Reviewer should create a review as part of the review process.
As mentioned above, don't commit and run. Try to be available in IRC after committing your changes, just in case something goes wrong or one of the developers or testers has a question.
Finally, once enough time and testing has passed, and you're reasonably sure the issue has been addresses, you should return to JIRA and "Resolve" the issue. Do not "Close" the issue - that should be done only by the QA reviewer, who should never be the original developer.

Developer Procedures