Development:Subversion SVN
From Wiki
Hello! You are visiting this page because you are interested in developing war3source under Subversion, or you are here to learn about Subversion.
For those of you that already know SVN:
Checkout URL: http://ownageclan.com/svn/war3source
Online SVN browser: http://ownageclan.com/websvn
Contents |
[edit] What is Subversion? (SVN)
Subversion is a version control system. It is a software that keeps track of changes of files over time. It also allows simplifies collaboration between multiple authors, and allows the latest version of the code be available instantly without a human to keep track of versions and merging files.
[edit] Why Use Subversion?
Why not use GIT HG or <name other software here>?
"Because SVN is simple and there's less ways which one person can screw up everything" - Professor Perkins
[edit] Stepping on each others' toes
Suppose two contributors of War3Source wanted to change the translation file "w3s.race.human.phrases.txt". Person A would take the translation file from the latest release, change it, submit a copy to the forums. One hour later, Person B would take a copy of the translation file, edit it, submit a copy to the forums. Ownz the main developer is met with a challenge. Two people submitted a revision for a translation file with some minor differences between them. Ownz had to pick an choose a file for the next version to release. Say he chooses person A's revision. Person B took all the effort to also translate the same file, but was not used in the end.
[edit] SVN to the rescue
If Person A and Person B used SVN, Person A could have copied "w3s.race.human.phrases.txt" from the latest release storage place (checkout the repository), edit it, then upload it back to the latest release storage place (commit to the repository). One hour later, Person B checkouts "w3s.race.human.phrases.txt" from the repository, sees that its nearly complete, edits a few words here and there, then commits to repository. Time wasn't wasted to rewrite the entire translation, and Ownz did not have to intervene or choose a revision to be included the next official release.
So we state the main reasons for using SVN:
SVN solves the problem of one person doing work that has already been done.
SVN allows a file to be easily reverted if a change is unwanted.
SVN tracks changes so those who want to see line by line changes can do so.
SVN allows simple file merging if two people worked on the same file.
SVN acts sort of like a backup system, if you lose your files, you still checkout from the repository and get back on your feet.
SVN allows you to move from computer to computer and work the the latest code without manually transferring them.
[edit] SVN Technical Terms
You are going to encounter some terms on while you are using SVN. These terms are by no means hard to understand once exposed to. Here are the ones you must understand:
repository: The place where the latest up to date code is stored. Like a filing cabinet. It's identified by a url like http://www.blah.com/path
HEAD: The latest revision in the repository.
checkout: first time downloading the repository to your local folder.
working copy: the local folder where you work on the versioned files. Your working copy may not be the same as the HEAD because you may have changed your files or HEAD was updated and your working copy is "out of date".
update: updating your working copy to the latest revision on the repository.
commit: updating your working copy to the repository.
[edit] The SVN workflow
This is a very quick introduction, detailed sections are below, make sure you read all of it carefully.
So you want to change some files, or even add some new files to the latest code base, what do you do?
We will show you how it works, then show you how to do it.
In short, we:
checkout into c:/somefolder //It copies all the files on the repository to your local folder
change file c:/somefolder/somefile.txt
commit c:/somefolder to repository //we put our changes onto the repository, the revision number on the repository changes
Say the next day you want to change some other file, you don't checkout but you update instead because you already have a working copy.
update c:/somefolder //It updates all the files in your folder that have been changed on the repository since the last time you updated or checked-out.
change file c:/somefolder/somefile2.txt
commit c:/somefolder to repository //we put our changes onto the repository, the revision number on the repository changes
[edit] The SVN Client
This tutorial is geared toward windows users. The chances are, you are using a windows machine and want to learn how to use SVN. If you are on linux, you are out of luck as Ownz does not bother with SVN usage on linux via command line (see image on left). However, you can still follow this tutorial and understand the general operations of SVN, and then use it in your linux environment, with a different SVN client that comes with a GUI. If you know command line that's fine too.
The SVN client we will be using in this tutorial is TortoiseSVN. Go download and install it right now! TortoiseSVN is the most convenient SVN client because it directly integrates with your windows explorer shell. It overlays icons in your folders, and access to SVN commands are in the right click context menu.
Compare the different procedures between windows TortioiseSVN and linux command line. Detailed instructions are given later, this is just a comparison.
| Windows (TortoiseSVN) | Linux command line |
|
Browse to folder a folder. | $ cd /path/to/project $ svn checkout http://www.blah.com/stuff
|
From now on we will only talk about SVN operations via TortoiseSVN client.
Once TortoiseSVN is installed and you have rebooted, windows explorer will integrate overlay icons to easily help you identify files that are under source version control. TortoiseSVN has these overlay icons:
What you want is the green check (normal) which means the file is up to date with the repository.
The other ones you will encounter are:
modified (!), non-versioned (?), ignored (-)
For more information on these overlay icons, visit http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-wcstatus.html
[edit] Using SVN
Now that we have our SVN client installed, lets get hands on with SVN.
[edit] Checkout
As mentioned before, the first thing we have to do when getting started with a SVN version controlled project is to checkout the repository.Since War3Source is a sourcemod plugin, we recommend you create a folder called War3SourceP inside the sourcemod scripting folder, as this is how Ownz and many others keep themselves organized. Paths listed are relative, for example .../scripting/War3SourceP is whatever_your_actual_path is/scripting/War3SourceP
| Browse to /scripting folder Create a new folder called War3SourceP in /scripting |
Example: Checkout repository to War3SourceP folder
http://www.youtube.com/watch?v=ywbwbbS3064
If you checkout to a folder that already has content, SVN will try to merge. You need to be very careful when doing this. For example, if old versions of the files are in the folder, the merging process may add back the deleted parts that are not wanted and could conflict when trying to commit! We recommend you checkout to an empty folder.
[edit] Commit
After you checkout the repository, you may begin adding your work to the working copy.After you are finished editing the file, you can right click on the file(s) and click Commit, or go to the top level directory of your working copy (War3SourceP) right click and commit.
| Right click on War3SourceP folder, in the context menu click commit. Enter a message, a summary of what you have changed. In the window (see picture on right), you can select which files you want to commit. Click OK. Files will be updated to the repository. |
Example: changelog.txt has been changed, we commit it to database.
http://www.youtube.com/watch?v=VQNAaf4u944
You want commit to database often because you want everyone else to have the latest copy of what you are modifying. There are exceptions of course, such as you need more time to work on that file and it will not compile with the changes you've made so far.
If you have a question mark on your file or folder, that means the repository doesn't know what that file is. Like you created a new file for the first time. To mark this file to be added to repository on next commit, right click -> TortoriseSVN -> Add. You can also add files in the commit window:the place where it asks you select which files you want to commit. New files will be added if selected.
There are some files you don't want to add to repository, like compiled folder, or compile.exe, or your own race you are working on right now. You can right click the file ->TortoiseSVN -> Ignore. You can ignore by name or by extension.
If you checkout to a folder that already has content, SVN will try to merge.
You only checkout into a folder ONCE, getting updated revisions from the repository is known as an update (see below)
"SVN checkout is like losing your virginity, once you do it you can't do it again." - Professor Perkins
[edit] Update
When you already have the working copy, you don't checkout a repository to get the latest revision. You update the files to the latest revision instead.
To update:
|
Right click on folder War3SourceP |
You can update individual files, but we usually update the entire working copy.
AN UPDATE DOES NOT OVERWRITE YOUR CHANGES, IT MERGES WITH THE NEW CONTENT, see next section.
[edit] Updating a modified file that someone else also modified
What if you modified a file, then someone else modified and commited to the repository, and then you tried to update??
There are somethings that can happen:
- SVN merges it. That is, if the changes from you and the changes from the repository are obvious to TortoiseSVN, you will get the changes added to your own version of the file. This may or may not cause problems, so humans will have to be the judge if the merge should be reverted. Your changes to the file are not in the repository because you have not commited, you only received new lines in your file from the repository.
- SVN doesn't know what to do because the changes are in the same area, this is called a "conflict", see the next paragraph.
Upon a conflict, TortoriseSVN will create file.txt.rXXXX where XXXX refers to the revision number, it is the version of the file from the repository with other person's changes. It will also create and file.txt.mine, it is the file.txt before you tried to update with your changes in it. file.txt will now contain your changes and the other persons changes in a "conflicted" state, like this:
stuff some code blah blah
<<<<<<< .mine
your changes
=======
other person's changes
>>>>>>> .r189
stuff other code stuff
You will have to be the judge on how to solve this problem. If you don't understand the intentions of the other person's changes, you should go ask him why he made those changes.
- If you asked the other person and the other person accepts your changes, or you know you are right and the other person is wrong: you can delete file.txt, rename file.txt.mine to file.txt, right click on file.txt and choose TortoiseSVN->Resolved. Delete file.txt.rXXXX. Commit. You forcibly commit your version of the file to the repository. The other person's changes are not lost as it has been captured in a previous revision.
- If the other person's changes are better, you can delete file.txt, rename file.txt.rXXX to file.txt, right click on file.txt and choose TortoiseSVN->Resolved. Delete file.txt.mine. Commit. OR delete every file associated with the conflict ( file.txt , file.txt.mine , and file.txt.rXXXX), right click the current folder and choose Resolved, then update. You have removed your changes and received the latest file from the repository.
- You can collaboratively (preferred) or by yourself, edit file.txt and delete <<<<< or >>>>> and ====== selectively choose which changes are the best. When you are done, right click on file.txt and choose TortoiseSVN->Resolved. Delete file.txt.rXXX and file.txt.mine. Commit.
We directed you to commit in each case so that the latest is in the repository with your changes and or other person's changes.
[edit] Troubleshooting SVN
Even in a simple checkout/update then commit, SVN may not want to do what you want it to do, and spit out some errors. We suggest you google the problem. If that doesn't help, take a screenshot of the error and post the error on the forums and we will try our best to help you fix the error.
[edit] Wait! Someone overwrote my changes accidentally
SVN does not allow commits without an update to the latest revision. That means whoever commits is forced to merge with the HEAD. There are possible scenarios where one person changes something, commits. The second person updates to get your changes, but then when they commit they reversed what you have just done.
Culprits: The second person left the file open in a program like PawnStudio/PSPad. They updated the directory, but PawnStudio doesn't detect the change. When the user saves the file again, they save the old file. This new save counts as a change but contains an out of date version of the file which does not contain person one's changes. SVN thinks this is a change and will commit the old content without error.
Same thing could happen if a person manually kept a backup of that file somewhere, then pasted it back in the working directory. Again SVN thinks this is a change and allows it to commit. (This is actually how Ownz reverts changes)
[edit] Futher reading
Full SVN tutorial is at http://svnbook.red-bean.com/| Language: | English • Русский |
|---|
