svn usage 0.html - frc971/website GitHub Wiki

The Spartan Robotics Team uses Subversion (SVN/TortoiseSVN) to manage and share robot CAD, software source code, documentation, graphics, and other team files. 

Follow these rules whenever working with SVN.  This is especially important with SolidWorks CAD files.

Also be sure and check out this step-by-step guide to Subversion for use with the FIRST 971 team.  It tells how to check out the team frc971 repository.

If you have corrections or comments about these rules, please contact Brian Silverman and/or Michael Schuh.  February 7, 2012.

The SVN server is not an endless resource for saving files.  Only check these types of files into the repository.  People who don't follow these rules will lose their SVN server privileges.

• 971 Team CAD Files - parts and assemblies.  Don't check in temporary files with "~" in the names or STEP files.
• 971 Team Source code for the robot and drivers station.  Don't check in object files or executables or distribution files from other sites like WPILib zips or tar files.  Don't check in documentation that is available on other websites (e.g. WPILib documentation).  You can check in a simple Readme.txt or Readme.html files with directions and links to these resources, or better yet, update the build scripts to automatically download them when necessary.
  • Do not share team CAD or source code files with people outside of the team without first getting approval from the team Leadership Council.
• 971 art work used for the logos on the robot.
• Don't check in game documents or other files that are available on the web. 
• Check files into the correct place.  The repository has a very clear structure.  Use it.  Ask Brian, Austin, or Michael if you have questions about where to check in a file.
• If you are unsure about if a file is appropriate to check into the repository, then ask Brian, Austin, or Michael before checking it in.  The SVN repository is designed to permanently keep files.  The "svn delete" command does not delete the files from the repository.  They are always there once checked in.
• If you have a file that does not fit in the above list, and want to share it with the team, use Google Docs, Drop Box, or some other similar way of sharing.

• Close all open files in SolidWorks before doing anything with SVN, or else you are likely to need the "Fixing Hangs" section.
• Right click on the top level SVN folder and click "SVN Update".
• Type in your username and password if it asks.
• If there are any conflicts (it says "Warning! One or more files are in a conflicted state" in red in the update window), resolve them (see RESOLVING CONFLICTS).
• Make sure nobody else is working on the assemblies and/or parts you are going to edit.
• YOU ARE NOT DONE EDITING ANYTHING UNTIL YOU CHECK IN (see AFTER EDITING)!

• Close all open files in SolidWorks before doing anything with SVN.
• Right click on the top level SVN folder and click "SVN Commit..." (if it hangs, see FIXING HANGS).
  • Think about exactly why you are checking in. If you have just finished 1 file and are planning to work on more, you should not check in. Instead, if there is no reason to check in immediately, finish your work for the day and then check in.
  • If you didn't change any of the files that are checked, right click on them and click "Revert..." (and then click the top button that says "Revert").  This is important because it helps prevent conflicts and save server space because each revision of each file is permanent.
  • If you don't want any of the files that aren't checked (new files), right click on them and click "Delete" (and then "Yes"). If you just leave them on team computers, it is confusing to others who then do not know what to do with them.
  • Make sure to check the check boxes next to any new files you created or they will not be checked in.
  • Type in your log message.  Here is some guidance for creating a good and helpful log message:
    • A commit message should always describe what you have changed.  When writing a commit message, you should always keep in mind it's purpose.  The purpose of a commit message is to make it easier to find out when changes were made to files and folders.  When someone is viewing your commit message, it will always be along with the date and time of your commit, the names of all of the files and folders that were changed and how they were changed, the SVN username you are using, and all of the other commit messages in order.  This means that you should NOT put the full names and paths of all the files that you edited into the commit message!! Instead, you should put a description of what the goal of your changes was.  Also, saying "here are my changes" is not very helpful, because there is no other reason for a commit message. For example, instead of something like
         "Today (2/23/2011) I edited CAD/roller_claw_number_2.SLDPRT, CAD/roller_claw_assembly.SLDASM, and CAD/roller_wheels.SLDPRT and created CAD/roller_claw_reinforcement_piece.SLDPRT"
      you should write something like
         "Fixed some dimensions on the claw and added a reinforcement piece to it."
      because anybody looking at your commit message will be able to see that you modified those 3 files and created that one.  However, what they will not be able to tell without a lot of work is what your changes did (fixed the size and made it stronger).
  • Click "OK".
  • Type in your username and password if it asks. If you're on a team computer, do NOT check the box to save them. However, on a personal computer, checking that box is probably a good idea.
  • If it says (in red) that something is out of date, update (see BEFORE EDITING) and then try again. Sometimes, TortoiseSVN will offer to update for you.

• If any SVN dialog box hangs for longer than usual, right click on the top level SVN folder and go to "TortoiseSVN" > "Clean up..." and then click "OK".
• Right after doing this (as fast as you can move your mouse), do whatever you were trying again.
• It sometimes takes a couple of tries to get it.
• Also, there is an incompatibility between newer versions of TortoiseSVN and Solidwork on Windows 7 related to the preview icons on Solidworks files which results in the dialogs hanging all of the time. To fix it, download solidworks_registry_fix.reg and run it (as an adminstrator), clicking yes/ok/whatever to all of the Windows warnings (you can open it with a text editor to see what it's doing if you want).

• Go to wherever the file that has the conflict is (it might have a yellow! on it).
• There will be 3 files:
  • Just the filename, which is whatever you ended up with.
  • 2 files with .rxxxx appended to them.  These are the last file that you got from the repository and the file that is currently in the repository.
• Either rename the file with the bigger xxxx appended to it to the original filename or delete the 2 .rxxxx files, depending on which version you want to keep.

Repository

-The files and folders on the server that contain the all the revisions that have ever been checked in.

-You should never have to create one.

-Every repository has a unique URL that you use to check it out.

Working Copy

-The files and folders on your computer that you work on.

-You can have multiple ones in different locations on your computer.

-There will be a folder named .svn in the root (and maybe each subfolder, depending on what version of SVN you're using) of a working copy. You should never touch this directory.

-Each one has a URL which must be that of a repository or any folder in it.

Check In or Commit

-Using your client to send changes you have made in your working copy to the repository.

-You should write a good commit message to go along with it.

-Each commit creates a revision which is stored in the repository permanently.

-You should also write a good message to go along with it.

Update

-Using your client to download any revisions that have been checked in to the repository since you last updated or checked out a working copy.

-You can also update to a specific revision number to look at an older version.

Revision

-The state of all the files and folders in a repository at a certain point in time.

-Exactly one uniquely numbered revision is created for each successful commit.

Check Out

-Using your client to create a new working copy on your computer.

-You should not perform a check out into an existing working copy.

Conflict

-What happens when one person checks in modifications or deletions and another person attempts to check in changes to the same file(s) before updating their working copy.

-This is why you should always update before beginning to work on anything.

-With text files, your client will sometimes merge changes you have made with the ones coming from the repository. This is indicated with a "G" in the left-hand column where normally only "A", "U", and "D". If you see this with a binary file such as a solidworks file, then you should revert the file.

Client

-The software program that runs on your computer and communicates with the repository.

-While it usually interacts with a working copy too, most clients can list the files and folders at a given URL also.

URL

-In the context of SVN, a URL identifies a single file or folder in a repository.

-Each repository also has a URL, which represents the root folder.

-URLs in SVN always start with svn:, http:, or https:. It matters a lot which one of these it is. You can almost never check in to a http: URL because they are not secure. If you have a http: or https: URL, you can put it into the address bar of a web browser to view a file or folder without having to check anything out.

The Spartan Robotics Team uses Subversion (SVN/TortoiseSVN) to manage and share robot CAD, software source code, documentation, graphics, and other team files.