Subversion

The SF.net Subversion service page for our project contains the information needed to connect to our Subversion (SVN) repository. You may want to install one of the SVN clients listed on the [developer tools] page first. SF.net has a detailed wiki page about their Subversion offering where you can find the version of the SVN server software they are running. The free Version Control with Subversion book is an excellent source on everything related to SVN.

You can browse the repository online through the FishEye or ViewVC sites.

Version control

Also known as revision control or source control. Except being able to easily share code and other files, the purpose of a version control system is to track every change, every success and every mistake and store them ''forever''. It's like a time machine where you can go back to any point in time and observe the state of the project files exactly as they appeared back then. This allows us to refer to each set of changes (called "changeset" or "revision") and the state of the project files before and after the changes were applied. It also allows us to revert changes and revive previously deleted files. Just as Wikipedia asks its users to "be bold" and "take responsibility", similar principles apply here. Don't be afraid to improve code and remove old stuff. If your changes do not turn out as expected there is always a way back.

To "commit" (known as "check-in" in the VSS/TFS world) is when you upload your local modifications to the central repository, so that they are available to all other developers. Whenever you commit a set of changes, this set is given a unique ID called a "revision number", or just "revision" for short, in Subversion terminology. Use this number to refer to the set of changes you have made.

Try not to break the build

Before you commit you must take some steps to make sure that you '''do not break the build''' and end up giving other developers a nasty headache. You must ensure that

• The entire solution compiles without any errors.
• The entire solution compiles without any warnings, as far as this is possible.
• There are no [[StyleCop]] violations.
• All newly added, moved/renamed files are included. SVN has to be made aware of these changes. See the documentation for the SVN '''status''', '''add''' and '''move''' commands.

If you do break the build you should expect other developers to inform you of the situation. You might risk that the revision your committed is undone (reverse merged) so that other people can continue their work while you figure out what went wrong or other developers might throw in a quick-fix to get back to a working state.

Commit early, commit often

It is good practice to ensure that all the changes in a single commit are logically related and serve only a single purpose (SVN best practices). Try to limit each commit to a single bug fix or feature and avoid the temptation to bundle lots of unrelated changes. You are free to make as many commits as needed to get the changes you care about into the repository. If you are working on a big task you should consider breaking it into smaller logical units and commit them separately (or possibly create a feature branch).

Try to know your next commit and not let speculative changes slip into trunk. If you need to do experimental and highly invasive work you can create a branch so as to not disturb the other developers who are working in trunk. This way you can also get other developers to review your proposed changes before they are integrated into trunk. If the experimental changes leads you nowhere you can just throw away the branch.

Log message

Remember to write a brief description of your changes so that other developers do not need to read the diff in order to know what changes you have made. By following the guidelines above it should be easy to write a log message. If the changes are related to an issue in our issue tracker (bugs, features, tasks) you should refer to the issue ID (SF.net refers to this as "Artifact ID" or just "ID") in your description by prefixing it with "issue" or "Issue" and listing the issue ID as "#1234". Multiple issues can be listed by separating them with space, a comma or the word "and". The exact pattern the issue reference must match is specified by the regular expression in the bugtraq:logregex SVN folder property.

Log message examples:

• Issue #1234 solved by adding a missing mouse-click event handler.
• Fixed issue #1234, #2468 and #3210 regarding fleet transport.
• These changes correct issue #1234. As a side-effect issue #4321 is also solved.

We operate under the assumption that you are the original author of the work that you submit. In situations where this is not the case you must use the log message to clearly describe who the original author is, how to contact him/her and under which license the original author has licensed the material. Make sure that the license provided does not conflict with any of our existing licenses. If in doubt, ask in the developer forum. Never submit copyrighted work without permission from the original author. Sometimes it might be easier to get the original author to sign the Contributor Copyright Assignment Statement to transfer the copyright to the Stars-Nova project.

Now you can commit

If you have followed the above instructions you should now be in a position where you can commit your changes. Do that. Now :)

Ignore files

The SVN repository contains all source code, build scripts, graphical assets and other content needed to develop, build and publish a complete set of installation files for the game. Any files and folders that can be generated automatically during the build and publishing stages should not be included in SVN. These are often binary files (object files and assemblies) or files with settings that are only relevant for the current user or machine (Visual Studio .suo file contains absolute paths).

Some SVN commands will by default list any non-versioned files and folders if they are contained within an already versioned folder. It is possible to configure SVN to ignore these files/folders by using the property svn:ignore on the folder that contains the files/folders.

Examples of files and folders that we have made SVN ignore:
* '''Nova.suo''' is a local user options file generated by Visual Studio in the same folder as the solution file.
* The '''bin''' and '''obj''' folder inside each project folder contains binaries and object files generated during compilation.
* '''StyleCop.Cache''' is a non-essential file generated by StyleCop.
* MonoDevelop generates '''.resource''' files based on the original .resx files.

Branching and merging

Short story: With SVN [branching](http://svnbook.red-bean.com/en/1.5/svn.branchmerge.using.html#svn.branchmerge.using.create is easy, but merging can be difficult. Before you embark on this adventure you should most certainly read the Branching and Merging chapter in the free SVN book, or you are guaranteed to run into trouble. According to Subversion Best Practices our branching and merging practices roughly follows the Branch-When-Needed system.

In SVN a branch is nothing more than a copy of a directory. For organizational purposes branches are created under the /branches path in the repository. Almost all branches are created by using a specific revision of /trunk as the source of the copy operation and a new subdirectory under /branches as the destination. Only very rarely (or never) do we create a branch from another branch. For the purpose of keeping a clean and consistent branch we normally base a new branch on /trunk itself, and not a sub-directory.

There are mainly two types of branches:
* Release branches (like /branches/0.4, /branches/0.5 and so on) are used for stabilizing and preparing releases. They often apply the practice of cherrypicking to selectively include appropriate changes from trunk. This is especially true for successive bugfix releases from the same release branch (0.4.1, 0.4.2, 0.4.3 and so on) as the changes in trunk are sometimes geared towards the next minor version (0.4, 0.5, 0.6) and may not be compatible or appropriate to include in a bugfix release. As a release branch grows older it ends up diverging from trunk due to the revisions that are never cherrypicked (there is no remedy for this, thus is the life of a release branch). Release branches are never integrated back into trunk and changes are usually not merged from release branches into trunk.
* Feature branches are more free-form than release branches. Instead of living a life doomed to diverge from trunk a feature branch instead tries to keep in sync with trunk while applying its own set of changes. All changes from trunk (no exception) are regularly merged into the feature branch to prevent it from drifting too far away from trunk. Changes are never merged from the branch into trunk, except at the bitter end. A feature branch ends its life in one of two ways:
** Reintegrated into trunk. After making sure that the branch is in sync with trunk it is possible to merge all the changes made specifically on that branch into trunk. According to SVN merge tracking practices the feature branch should be deleted once it has been reintegrated into trunk. If you need to keep on working on the branch then a) you should not reintegrate it into trunk or b) reintegrate, delete the branch and create a new one from trunk.
** Discarded, deleted, eliminated, terminated. It could be abandoned and turned into a ghost town, but sooner or later someone will come along and end its miserable life.

There are a few things that must be taken into consideration when managing a feature branch:

Do not

move or rename files and folders in neither the branch nor trunk for as long as the branch is alive. This is a guaranteed way to cause tree conflicts during merging. SVN and almost all other open source version control systems, except Git and Bazaar, lack support for true renames (they are implemented as copy+delete).

Know how to resolve merge conflicts.

If you do not know how to do this then ask for help. Incorrectly resolving a merge conflict can cause all sorts of subtle bugs.

DO NOT MOVE OR RENAME FILES AND FOLDERS!

You'll pay through the nose (or we could change to Git or Bazaar which has true renames).