Please abide by these simple SVN rules, they will keep the server, the devs, and the users happy, sane, and updating at the best speeds the server can provide.
- 1 Checkouts and Updates (Downloading)
- 2 Committing (Uploading)
- 2.1 Getting an Account
- 2.2 Signing this page
- 2.3 One addon per commit
- 2.4 Path names
- 2.5 Commit Notes
- 2.6 Necessary SVN Properties
- 2.7 Do not commit to Addons that aren't yours
- 2.8 Don't spam
- 2.9 Test before you commit
Checkouts and Updates (Downloading)
So you've just started playing with the SVN, maybe with Tortoise SVN, and you just had a great idea pop into your brain...
- Why don't I just checkout the whole trunk folder?
Don't do it
Why? SVN checkouts require quite a bit more processing than a basic download from your favorite software archive does. Throw in our very generous use of externals and the load you place on the server compounds (1 addon checkout suddenly becomes 8 or 9 due to libraries). Please take the time to sort thru the SVN and checkout the addons you want.
Warning ~ Some SVN clients will attempt to checkout the whole repository when you first set them up... this should be avoided if at all possible.
As was just pointed out, externals can add extra load to the server. I know you're thinking Well if these externals are such a problem, why do you use them? Well, they are a tool to help the developers keep their libraries up to date, and we use a lot of libraries. The problem arises when mass numbers of users are checking out many mods with the same externals, and updating them over and over again. Externals are a tool for the devs, and we will continue to use them.
So, simple request to you users downloading with SVN clients, if you use a fair number of mods with externals, please checkout and update without externals. This helps lower the load on the server, keeps it speedy, and everyone is happy.
Now I know your first urge is to just select all and choose update. This is okay, if you don't do it often. If you are doing this more than, say, once a day, please take the time to watch the commit log or subscribe to the Google Group. Pay attention to what addons have actually changed, and only update those.
Perhaps this whole SVN thing is a tad complex for you, that's okay. We also have a stash of auto-generated zip files you can download from. Those zips update with every commit, and versions without externals are generated as well.
There are some auto-updating scripts in the works that will use the zips, please stay tuned!
Getting an Account
Got an Ace addon you'd like to add to the SVN? Feel like translating a few mods into your local language? Just want to help keep your favorite mods updated? Make sure you read this whole page, sign (on the Talk page), and then contact the Ace Admins for an SVN account. Make sure you explain who you are and why you want write access to the SVN. You need to include what username you'd like to use. We'll contact you with further details.
Signing this page
You must sign this page before you will be granted an SVN account, and if you don't stick to these rules we'll do bad things to you in your sleep. To sign that you have read this page, visit Talk:SVN Rules, edit the page, and add
--~~~~ at the end. This will automatically put your username and timestamp in.
One addon per commit
Simple rule, one addon, one commit. Don't commit multiple addons in the same operation. If you didn't check out the entire repo, this shouldn't even be possible for you anyway. There are some special cases where authors will mass-edit many items in the repo. Please do not do this, those who do know what they're doing, and it's usually a change that must be applied to everything in the repo (like correcting externals after the server move).
Second simple rule, use consistent path names. We have a lot of addons on our SVN, we need to keep them in order. You should only ever commit into one of three paths: trunk, tags, or branches. For each of these examples I will use a fictional addon SomeMod
- This is where the "main version" of your mod should go. The current build, if you will. This path is simple:
/trunk/<addon name>/<addon name>.toc /trunk/SomeMod/SomeMod.toc
- Tags are a sort of snapshot of your code, a bookmark if you will. Most authors will tag specific milestones in their code, major versions, release candidates, even the final build of an abandoned project. You are encouraged to tag your mods as often as you want, even if it's just some simple reminder to yourself. Tags follow a slightly different path:
/tags/<addon name>/<Tag name>/<addon name>.toc /tags/SomeMod/v1.0/SomeMod.toc
- Branches are a sort of "side development" from the trunk. An author might branch their addon to convert it to new libraries, or another author may branch to give some code rewrites to another author. We highly encourage the use of branches to share changes to other authors' works unless you already have consent from that author to edit their trunk versions.
- Branches have a naming scheme similar to tags. The branch name is, in most cases, simply your user name:
/branches/<addon name>/<Branch name>/<addon name>.toc /branches/SomeMod/Tekkub/SomeMod.toc
Every commit you make will ask for notes. Do not leave this blank. Commit notes should always contain the name of the addon you're editing at the start. This is followed by a description (simple or long) of what changes you made. Most authors will use a format like:
SomeMod: Updated externals
SomeMod - Fixed nil error on line 42
If you keep with this format, commit logs are much easier to read. Also, commit notes should always be written in english, because alot of people from many countrys use the SVN.
The SVN will now actively reject commits to trunk that have bad notes. To ensure that your commit is accepted, the note must begin with the addon's folder name you are committing to. For example, if you are committing to /trunk/SomeNeatMod/modules then the commit note must begin "SomeNeatMod ..."
In the rare case you need to commit to trunk but your note does not start with the addon name, you can override the filter by using . as the first char of your note. If this feature is abused, it will be removed!
Necessary SVN Properties
Every added text file must have the svn:eol-style property set. A pre-commit hook will prevent the commit if it is not set. We also advise that svn:mime-type be set, but it is not a requirement for text files.
See SVN AutoProps for information on how to automatically set the necessary properties when you add new files.
If you'd rather do it manually:
Try setting the 'svn:mime-type' property to 'text/plain' and the 'svn:eol-style' property to 'native' (or your preferred line ending setting).
Do not commit to Addons that aren't yours
What am I talking about? You see a typo or quick mistake in another mod. You urge is to fix it or patch it. No big deal right? Well the problem comes from people doing much more drastic things to other people addons, like rewriting huge portions, or adding major features.
This is just a BAD idea. Don't Do It!
If you have something like this going on my first recommendation is to create a diff or patch file and send it to the respective author. Let them be the ones to decide if and how the patch gets implemented. If they ask you to commit the fix then that is one thing, never do it without permission!
In the past, we have had to revoke SVN rights of people doing mass commits to addons without asking their authors. We will do it again.
THIS INCLUDES TOC INTERFACE VERSION NUMBER INCREASES!
If it's not your addon then do NOT bump the TOC after a patch. Even though an addon may seem to be working fine to you it doesn't mean it should be advertised as compatible with the latest version of WoW. There may be issues that could only be known by the author that you may not notice. Abandoned addons should keep their out of date TOCs so people can tell that they haven't been updated recently.
People won't stop editing my project, Help!!!!
Ok! All you had to do was ask! Send an email to firstname.lastname@example.org and tell us! You need to include the name of the project, and what author(s) should receive access. Please keep in mind that we have to have the corresponding svn usernames.
If you are making many changes to a mod, please make all the changes and test them for simple syntax errors before you commit. Every commit message is echoed into the IRC channel, and we don't like it when a bunch of tiny edits on the same addon spam up the place. If you are making the same change across many addons (like TOC version updates), please space out your commits a little bit. This will not only reduce the spam, but it'll allow the server a moment to run it's post-commit scripts. If the edits are minor and don't effect performance (like TOC version changes), you might be better off just waiting until you have a significant change to commit up.
Test before you commit
This one's a simple request, compile/build your code or log in to the game to check for simple syntax errors before you commit. This will reduce "fixed typo" spam commits a great deal. If you're coding somewhere where you cannot test like this (say at work or the in-law's house), then you should probably note in your commit message that these changes are "drycoded". This tells other authors and users that the code will probably be buggy since you could not test it.