How to Use the SVN, Github, Twitter, and AML_Backup
In your daily work, ALWAYS create and name things (files and folders) as if they will last forever, because they usually do. Use descriptive files names
and add "readme" files when valuable. Comment your code and your experiments! The point of archived materials
is so somebody else can find it, not you. (But these rules will help you keep track of your own work, as well!) Use the SVN, Github and Twitter and other backup structures with other people in mind.
What is SVN?
There is not room here to provide a full tutorial on TortoiseSVN and the subversion
version control system (VCS). The
TortoiseSVN for Windows Docs can be found here. A few things that are important to understand include the fact that TortoiseSVN is NOT a program that appears on the Windows Start Menu. Instead, TortoiseSVN is a shell extension, the menu for which appears when you right-click on a folder representing an SVN repository. A CRL repository has been set up by ECN with an SVN server that provides access to all the files within the repository, but you can't edit the files directly. Instead, the first thing you must do is create a working copy of the files you are interested in ON YOUR OWN HARDDRIVE. This allows you to edit and test files LOCALLY without affecting anyone else in the lab. I generally make a working copy of the entire repository, but you can also choose to make only a branch of the tree, such as "CRL/Projects/HexRotor" if you are working on the Dexterous Hexrotor project, for example. (This is not what I recommend, as it leads to many copies of branches that can get out of date.)
It is NOT recommended to open the repo-browser and drag-and-drop files from there. These are not easy to maintain and track. Instead, you should check out a working copy, as described below:
To create a working copy on your own computer or lab computer, you must first have access to the repository that ECN has set up for us. THIS REPOSITORY MUST NEVER BE EDITED DIRECTLY!! To gain local access, you must first get permission to access the repository (see the Lab Manager) then set up a virtual drive
that points to the repository. Right-clicking on your "computer" icon, use "Map Network Drive..." to map "\\techstor1.ecn.purdue.edu\voyleslab" to "Z:". Check the "Reconnect at logon" box. (You should click "different credentials" and use your CAREER account info if installing on your laptop.) REMEMBER: Never edit or change any files or folders on the Z: drive!
Now, create a new folder called "CRL" on your local computer to create the working copy. (Never create a working copy on the Z: drive!)
Care should be taken when choosing a location for the working copy. As noted above, it should NEVER be placed on the Z: drive and the notion of a "local working copy" should preclude
placing it on any network drive. (Network drives are, by definition, not local.) Also, the current version of the file structure is approaching 100 GB, so if you place it in your roaming
profile, which includes your desktop when logged into an ECN machine, you will exceed your roaming profile storage. Good bets for your working copy are on a local C: drive or equivalent or under
"C:\Temp" on an ECN-maintained workstation.
Once you have created your local CRL folder, right-click the folder and click "SVN Checkout..." and enter "file///Z:/CRL" in "URL of repository" for a copy of the entire repository. (Or, enter "file///Z:/CRL/Projects" to get only the projects, for example.) Click "OK" to start to create the working copy and populate it. (This might take a long time.)
Once you have made and thoroughly tested improvements to a shared file or folder, you can "check them back in" to the repository -- overwriting the prior version in the latest repository with your updated files -- by right-clicking "SVN Commit..." Be sure to include a message about what files/folders you changed. Other labmates will be able to update their local working copies by right-clicking their folders and selecting "SVN Update".
An RCS implies that all revisions are tracked and stored forever. Once a file is updated in the respository, previous versions are available by using the "Repo-broswer" tool. This drammatically
increases the disk space required to maintain the repository, so be responsible.
What is Github?
Github is a commercial service and is essentially identical to the locally maintained CRL SVN. Both were launched in roughly the same year: 2007/2008, but SVN software pre-existed the CRL SVN repository by several years.
Both systems provide revision control for software and databases and such as well as a server to hold the repository. Github is owned by Microsoft and uses Git as its VCS on top of Microsoft cloud servers. The CRL SVN uses Subversion (SVN) as its VCS and the
server for the repository is stored and maintained locally. Git is a distributed VCS, while SVN ("Subversion") is centralized. A key difference is that SVN allows one to make a local repository of a single branch of
the repository tree, while Git does not. This is particularly good for laptop use, when you may not want to store the entire repository locally, or if you are in a hurry and want to take an entire segment of the tree with you, "just in case" (but no time for the whole tree).
General rules to follow in CRL
Follow existing naming conventions. For example, directories with images should be labeled "Images", not "images" or "pics"
or whatever. If you don't know what to name a directory, explore the structure to see what other names are used
frequently. Never use your OWN NAME for a folder name or file name. Always use meaningful names! ("IMG_25479" is NOT a meaningful name for an image on the SVN!! Nor is "Jaewooks_files" because none of you know who Jaewook was or what he worked on.)
Follow existing conventions on content, too. Remember, this is a shared respository! You are not the only user
and it is important to your colleagues that they be able to find what they need. Before you copy a new file or directory
to a shared repository, look around to make sure it is a reasonable thing to put there. Also, avoid putting
multiple copies of the same thing in different locations unless there is a clear reason to do so and it is
documented. (For example, pbort.c appears in many locations for completeness of code repositories, but the
appropriate version number should be documented in the master source files.)
Directory Structure
The following root directories contain the bulk of our files (use UpperCamelCasing for Directory names, lowerCamelCasing for file names):
Projects
Subdirectories under the "Projects" directory contain the bulk of the work of the CRL's various research projects
underway. Think carefully before adding a folder under Projects. Is it really a separate project? Does it really
deserve its own folder or is it part of another project?
Careful balance is key because we don't want large numbers of project files to proliferate to confuse us with
dead end projects. At the same time, we don't want to hide meaningful projects under too many levels of the
file hierarchy.
Pubs
These are publications and they are beginning to be organized by topic at the top level. Look for directories such as "Control_Architecture", "Robotic_Materials", "Theses", etc. Under these topics, folders are generally designated with the conference and year, as "ICRA2019". (If there are multiple
papers presented at ICRA 2019, then create multiple ICRA2019 subdirectories under the appropriate topics or, if related to the same topic, create multiple subdirectories under ICRA2019 with sub-topic titles.) Don't vary from the naming convention to create
"ICRA2019paperA" or something like that. "Control_Architecture/ICRA2019/RecoNode" and "Control_Architecture/ICRA2019/ReFrESH" would be good
subdirectory names. Try to avoid using grad student names because future students may not know who you are.
Also, don't vary the convention by using "ICRA19" or "RobAuto2019". If a conference is known by its name, use its
name: "RoBio2019". If a conference is known by its acronym, use the acronym: "IROS2019".
Generally, the Pubs directory is for published papers only, as papers that are not yet accepted should appear in your User directory. In some
cases, to promote file sharing of collaborative work, for example, it may make sense to use the backup structure for
work in process.
Refs
There may be a sub-directory for references (citations) used to support a particular line of work. This should be
titled "Refs". Use an abbreviation of normal scholarly citations in your file naming conventions. For example, file names
should approximate the form "MajorAuthors.Venue.Subject.pdf". When forming the filename, don't put every author as it will
get too long. Also, try to put the major professor first, as he/she will be recurrent, but include the major student,
as well. Same with the subject or title. Make it easy to search using important keywords, not a full description.
Embedded Virtual Machines for Robust Wireless Control and Actuation by Miroslav Pajic and Rahul Mangharam, in
2010 16th IEEE Real-Time and Embedded Technology and Applications Symposium would be titled something like
"MangharamPajic.RTAS2010.EmbeddedVirtualMachine.pdf". Spaces are optional.
This would be distinguished from Embedded Virtual Machines for Robust Wireless Control Systems by Rahul Mangharam and
Miroslav Pajic, in 2009 29th IEEE International Conference on Distributed Computing Systems Workshops as
"MangharamPajic.ICDCS2009.EmbeddedVirtualMachine.pdf".
Proposals
This directory contains selected proposals for research done by the CRL. Generally students will not be posting
to this directory, but are free to examine files within. Consider this directory confidential! (It not only outlines
our future work, but could contain the future plans of our collaborators.) These proposals
provide important insight into the work you are expected to perform. You should be familiar with the proposals
related to your projects.
Users
This is where you can bend the rules a bit. You can create and organize your User subidrectory any way you want, with the
caveat that the back up is still for other people. The CRL/User space should not be used for local junk. Use your
local drive for that! The CRL/User space is for stuff that is not quite ready for prime time, but could be valuable
to you or others. Think of it this way: If you got hit by a bus tomorrow, what would your replacement need to
complete your work? Put that in CRL/Users/YourName!
Superfluous Files
Never include superfluous files in the backup stream (SVN or static directories). This wastes space and
confounds collaborators. Do not include MS temp files (such as ~ files). Do not include LaTex files such as
.aux, .log, .bbl, etc. Only important files such as .tex, .bib, various image files, and maybe .tcp files
should be included. This is particularly true of videos. If you gathered a bunch of video to edit a conference video or some other important venue, make sure you save the source content. However, the various source clips that went into an edited video are often better stored under your user storage in "CRL\Users\Your_Name". Put the finished video in "CRL\Projects" as appropriate. Think carefully about saving stuff you didn't use. Only commit to SVN if it is truly valuable AND NAMED PROPERLY.
Prof. Voyles' Home Page
rvoyles [at] purdue [dot] edu
Last modified on: Jan 20, 2019