View source for SVN for School Projects

''Work in progress, please help make this page more useful for students''
=What is svn?=
[http://svnbook.red-bean.com/ svn (Subversion)] is a source code repository. It is a program capable of storing the source code of a project and keep track of all the changes made (contributions) by its developers.
===What svn can do for you?===
* Stores your work (source code) safely on a remote server so you will never lose your work.
* Lets several students work on the same project at the same time.
* Keeps track of all the work done with history (who have done what, and when), this means you can:
*: undo your work to any of the past stages of the work.
*: look at different stages of the work and see all the changes.
*: check other team members' work, their progress and contribution.
*: ask for help from others to help you with your work and help others with their work.
* paper less assignment submission
*: by tagging your work, your professor can
*:# checkout and evaluate your work
*:# mark your assignment fairly since each student's contribution is tracked.
*:# help you with your assignment by commenting and correcting your work remotely

=Common actions for school projects=
==Kick-start a project (project initiation)==
# create a directory to do your work
# checkout the repository (the whole thing) into the directory
#: Look and make sure you have the 3 directories (branches, tags, trunk)
# Open branches directory and create a directory using your login name
#: this becomes the root of your (each students') workshop
#: ''' note: do not use the operating system's file management to copy, move, etc any of the '''''versioned''''' files
# Do an update on the whole repo to see all the changes from all students
# branch the trunk into a sub-dir of your workshop (name the sub-dir using your assigned task)
#: branch as verb, means copy (in repository)
You are good to go to start working on your repository

==Start working on a project (Start a task)==
# If you have not already branched the trunk:
#: branch/tag the trunk into a sub-directory. Use your task name/description to Name this sub-directory so you can refer to it easily later.
# In your branch/task directory do your work and commit anytime you have something worth committing. Make sure you comment your commits. 
#: '''Note that in your branch you can commit your work even if it is not complete. In fact, commit your work anytime you are leaving your computer and comment it like: "going for lunch". But again this is only valid when you are working in '''''YOUR OWN BRANCH''''' 
# When task is complete 
## Update the repository to get all the changes applied to your local copy
## Merge the changes back to trunk 
#: Note that, the merging happens on the local copy and not the repository 
# Edit possible conflicts, save and mark them as resolved when done.
# Compile the trunk, test and make sure the changes are what you want
# In trunk, apply more changes and do debugging if needed.
#: note that this is the only time you do work in trunk
# When everything is perfect get ready to commit the trunk:
## Make sure you are logged in to IRC.
## Go to team page and set the status of trunk to committing with following info: User ID, email, IRC Nick, time and date
## If the status of trunk is already committing by another user, communicate with them and find out when they are going to be done so you can do your commit.
##: ''Never commit to trunk with out checking and setting the status of trunk in your team page''
## Update repository
# Commit the trunk
# Edit, save and resolve possible conflicts and go to previous step
# When done, go to team page and set the status of trunk back to committed with the same info as before.

==Continue working on a task on a new computer (public computer)==
# Checkout only your branch/task
# start working on your task and keep committing the changes as you go.
# when done, do final commit, stating the work period is done
# Delete the checked-out  directory from the public computer.
# '''''Reboot the computer'''''
#: this will remove your userid and pass if you have chosen to save them.
#: Note that you are responsible to keep you work safe, if someone gain access to your code and repository, YOU are responsible for it and its consequences.

==Continue working on a task (everyday work)==
# Update repository to get the final changes.
# (optional and only if needed:) If trunk is updated by someone else since the time you branched it, you can merge the '''updated''' trunk into your branch to get the latest additions and modifications of trunk in your branch.
# Continue working on your task and keep committing often.
# when done for the time, commit your work and comment, stating at what stage you are.

==Release a completed task (Submitting an Assignment or a Release)==
# This is when a major task is accomplished and it is time to present it to your professor.
#: This is not necessarily to hand in a new release. It could be at any time you feel you are one step closer to the end of the project.
# Update and make sure the trunk has the latest modifications.
# Do all possible changes and fixes to make this release final.
# tag (branch) the trunk into a sub-directory in '''tags'''. 
#: Name the tagged directory relative to its state (i.e. name it '''R0.4''' and comment it with task name '''Text Editor''')
#: If this is a fix to a previously released trunk, add the release revision after the release number: (i.e R0.41 and comment it as '''Fixed backspace bug in Text Editor''')  
# your prof will later update the repo and get the Release.

=Standard svn tree structure=
=== Directory Structure ===
<big><pre>
|-- Team_Repository_Account
  +--branches
  | +-- member-id1  <-- this is a team member's home within branches
  |   +-- Task1
  |   +-- Task2
  | +-- member-id2  <-- this is a team member's home within branches
  |   +-- Task1
  |   +-- Task2
  |   +-- Task3
  | +-- member-id3  <-- this is a team member's home within branches
  |   +-- Task1
  +--tags
  | +-- R0.1
  | +-- R0.11
  | +-- R0.2
  | +-- R0.21
  | +-- ...
  | +-- R0.5
  | +-- ...
  | +-- R1.0
  | +-- R1.1
  | +-- R1.2
  | +-- R1.21
  +--trunk
</pre></big>

==== branches ====
* '''branches''' is the common directory for all team members' workspaces. 
* Each team member should create their own home directory or '''workspace''' (member-id1, member-id2,...) for their own development tasks within '''branches'''. 
* Each team member should divide their workspace into several sub-directories (workspaces) during the development of the project. These workspaces(Task1, Task2, ...) are usually copies of the '''trunk''' to be worked on.
*: ''These sub-directories(Task1, Task2,...) are called branches of trunk. When the word '''branch''' is used as a verb, it means copying the whole '''trunk''' into a sub-directory, in '''branches'''.

==== tags ====
* '''tags''' is the directory that holds '''copies''' of successful stages of '''trunk''' throughout the development of the project. (''Also called as '''Milestones''''')
* '''tags''' are never modified or edited. ''You may branch a directory of tag into branches under a workspace and then modify the branch and apply the changes back to trunk, but you should never change the contents of a tag''
*: When the word '''tag''' is used as a verb, it means copying the whole trunk into a sub-directory, in tags.
* The action of '''tag'''ing the trunk into '''tags''' is often referred to as a '''release'''.
* We use the '''tags''' directory to submit the work for marking. ''Your instructor will specify the requirements of a release.''
** A release is usually tagged by a version number like: R0.1, Prj0.2, As1_1.0 
** When a release is due, your instructor will always mark the latest version of that release. 
**: ''If R0.3 is due, and R0.3, R0.31, R0.32 are present in '''tags''', then your instructor will mark R0.32

==== trunk ====
* '''trunk''' is the directory that holds the project in its current stage, '''complied and run-able'''
* '''trunk''' should never hold non-compiled code. Usually trunk is an exact copy (or better than) the latest version in '''tags'''.
* If the repository only contains one project, then trunk has no project level sub-directory and is the root of the project.  If the repository holds  more than one project, trunk is divided into several sub-directories - one for each project.
*: ''In this case, we divide '''tags''' into exactly the same project sub-directories as present in '''trunk'''''

=Svn basic commands=
A few important facts and terminology to help clarify the basic actions:
* A code repository is to keep track of all of the modifications done to a project by its team members. 
*:In a project that is tracked by a code repository (version-controlled or in short versioned), you can focus on any changes during the project's development life; such as, who modified/added/deleted what and when. You can undo work or rollback the work to any stage of the development and much more.
* SVN is a client/server repository;
** Code is kept on a server and those members who have access can copy the whole or parts of the project to their local machines, work on the whole or parts and then apply their changes back to the server.
** Because the code is kept on a server, one member may be unaware of the changes made by another member, unless the other has applied the changes to the server and the member has update their local copy. 
**: That is why timely and often communication between team members is highly vital for the success of the project.  This can easily be accomplished through the project wiki page (team page) and IRC
* A code repository manages merging the modifications of different members' code. However this may fail and as a result the repository will sometimes be in a conflict state.
*: Conflicts can easily be edited, saved and resolved using the tools provided by SVN.
* A '''Version-controlled or versioned''' file is a file that is handled and tracked by a repository.
<hr>
* For all the command lines below, note that if the userid and password is not set to be saved in svn, then you need to add
<big><pre>
 --username stdId --password stpassword
</pre></big>
to the end if each svn command. (userid and password '''IS''' set to be saved by default, make sure to reboot your lab computer for the uid and pass to be removed)



== checkout ==
To '''checkout''' is to download the code from a repository server as a whole, or partial, to a versioned directory on the client, so that you can start working on the code.
*GUI: 
# Create a directory on your local machine
# Right click on the directory and select '''SVN Checkout'''
# Enter the path of the repository or a sub-directory inside the repository and click OK
# Enter userid and password if needed
*Command Line:
<big><pre>
svn co svn://zenit.senecac.on.ca/repoid local_directory --username stdId --password stpassword
OR
svn checkout svn://zenit.senecac.on.ca/repoid local_directory --username stdId --password stpassword
</pre></big>
== commit ==
commits (submits) the changes in the local files to the repository (on server)
* GUI
# Right click on the directory or file to which you made modifications and click on '''SVN Commit'''  
# In Commit Dialog box write a short description (few words) to explain what is modified and is being committed and click on ok.
* Command Line
<big><pre>svn commit locdir\branches\stdId\SomeDirectory 
 -m "Added comments to foo() in faa.cpp and fee() in boo.h"</pre></big>
OR
<big><pre>svn commit locdir\branches\stdId\SomeDirectory\somefile.cpp
 -m "Added comments to foo() is somefile.cpp"</pre></big>
== update ==
Downloads and applies the modifications made by others from the repository (on the server) to the local files (on your computer)
* GUI
*: Right click on the directory or file (that you want it to be updated) and click on "SVN update"
* Command Line
while in the local directory 
<big><pre>svn update</pre></big>
OR from anywhere
<big><pre>svn update LocalDirecotyPath</pre></big>
OR for a single file
<big><pre>svn update LocalDirecotyPath/somefile.whatever</pre></big>
== '''branch'''ing or '''tag'''ging ==
To branch or tag is to '''copy''' one directory into another. The purpose of the copying dictates calling it '''branch''' or '''tag'''.
*To '''branch''' is to '''copy''' into '''branches''' directory for development
*To '''tag''' is to '''copy''' into '''tag''' to release the next stage of your project (also called to release a milestone)
*GUI, Branching 
# Right click on '''trunk''' in your local repository files and under the "TortoiseSVN" sub-menu click on "Branch/tag"
# Click on the button at right side of '''To URL''' and browse and find your '''workspace''' under branches directory (i.e. ''svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId'') and select it.
# Add the branch name (that is usually the name of the task to do) to the end of the selected path: ''svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/'''nameOfTask'''''
# In '''Log message''' type ''"Branching to do what ever task that is to be done"''
# Leave the rest of the options to remain as they are and click on ok.
#: This will make a copy of trunk under your '''workspace/nameOfTask''' on the server.
*GUI, Tagging
# Right click on '''trunk''' in your local repository files and under the "TortoiseSVN" sub-menu click on "Branch/tag"
# Click on the button at right side of '''To URL''' and browse and find your the '''tags''' directory (i.e. ''svn://zenit.senecac.on.ca/oop344_113repXX/tags'') and select it.
# Add the tag name (that is usually a release id like R0.6) to the end of the selected path: ''svn://zenit.senecac.on.ca/oop344_113repXX/tags/'''R0.X'''''
# In '''Log message''' type ''"Tagging release whatever"''
# Leave the rest of the options to remain as they are and click on ok.
#: This will make a copy of trunk under your '''tags/R0.X''' on the server.
'''''Note that this will happen on the server; therefore to actually have this applied your local copy, you should update your repository (for this see [[#update|Update]])
* Command Line, Branching
<big><pre>svn copy svn://zenit.senecac.on.ca/oop344_113repXX/trunk 
              svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/nameOfTask 
              -m "Branching to work on whatever task"</pre></big>
#* Note that the type of branching we use in here is called [http://svnbook.red-bean.com/en/1.5/svn-book.html#svn.branchmerge.commonpatterns.feature Feature Branch]
* Command Line, Tagging
<big><pre>svn copy svn://zenit.senecac.on.ca/oop344_113repXX/trunk 
              svn://zenit.senecac.on.ca/oop344_113repXX/tags/R0.6 
              -m "R0.6 is released"</pre></big>
== Merge ==
To merge, is to merge back the changes made in a branch in the '''branches''' directory.
*GUI
# First [[#update|update]] the whole repository.
# Right click on trunk and then in '''TortoiseSVN''' sub-menu click on '''merge'''
# In merge options, select the second one that is '''Reintegrate a branch''' and then click on next
# In '''From Url''' browse and find the branch you just completed your task on and then click on next. (i.e. svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/nameOfTask)
#: If browsing is not available you can use the '''repo browser''' to find the path to the branch and copy and paste it.
# Before merging you can click on test merge to run a simulation and see if the merge is successful
# click on merge to merge the branch back into trunk. 
#: note that the merging is happening on your local copy of the code and not the repository
# Edit and resolve possible conflicts
# Compile and test the trunk
# communicate with other team members and make sure no one else is committing to the trunk.
# '''[[#commit|commit]]''' the changes to trunk 
# Note others team members that the commit is done!
*Command line
Follow all the precautionary steps stated above and then:
<big><pre>
cd locdir
svn update 
cd trunk
svn merge --reintegrate 
    svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/nameOfTask 
    -m "merging back the comments to trunk"
</pre></big>
* Compile and test the trunk
<big><pre>
svn commit -m "committing comments added to CFrame"
</pre></big>
== Demo ==
Here is a [http://www.youtube.com/watch?v=ANFTtpGSOgM video demonstration] for using svn thanks to [[User:Tvirutthasalam|Thevakaran Virutthasalam]]