Project

General

Profile

Knowledge Base »

Subversion and Repositories

All projects use the Subversion tool for version control of key project files. These are stored in a 'repository' on the same server as the Electronic Design Notebook system. All project work for a given semester is to be done in the 'working' folder (see below). At the end of the semester, each team is to create a project archive or 'tag' (see below). This tag is a snapshot of the semester's work and allows future teams to see the exact project status at the end of each previous semester.

Basic How To Guides

  • Ian Keyworth, one of our students, took the available materials and generated a short quick start guide. Subversion_Quick_Start_Guide_for_Dummies.docx Note that the guide covers
    • checking out things from Subversion
    • initially creating a repository / repository structure.
  • Junichi Kanai put together this short instruction on using Tortoise to obtain usage statistics on Subversion to help monitor team progress and activity - Using_TortiseSVN_for_Evaluation.pptx

Common problems students encounter, and how to solve them:

How should I interact with files in SVN? - Install a Subversion Client
I can't commit a file
There is a conflict
How to run Cleanup?
Our team wants to use Git instead of SVN
How to EASILY access newest version of Capstone Playbook

Subversion / Tortoise / SvnX complains about a security certificate

If your subversion client complains about a security issue, you will have to first install the subversion client (see Install a Subversion Client) then run the following command in the terminal window using YOUR project's project-identifier. Note that "svn" is the command line command for running Subversion.

Subversion Clients

Interacting with your project's Repository through a browser is possible, but cumbersome. We strongly recommend installing a Subversion Client to allow smoother file use.

Repositories / Repository

Repository Contents

Examples of information that should be in the project's working folder on the repository are:
  • Design Documents – CAD database and drawings, circuit diagrams, system block diagrams and engineering specifications
  • System Evaluation – Test procedures, test results including raw data, and software used to analyze the results
  • Reports, and presentations in addition to the final output – Each phase of the Design Report (SoW, PDD, Final), preliminary and final presentation, preliminary and final poster
  • Needs & Requirements workbook – A list of needs, customer requirements, and related material, such as use cases.
  • Design Analysis – Simulation software and results
  • Prototype System (Components) - Software (source code) and a user manual

It is CRITICAL to remember that there should also be threads created in the Forum to document the reasoning and discussion about files in the Repository. This will help explain to teammates, clients, and instructors WHY a CAD model looks like it does, or WHAT additional work is needed on a spreadsheet calculation.

Naming / Location

All our repositories are managed by EDN and can be found at: https://designlab.eng.rpi.edu/svn2/repo-name/working where repo-name is the name of your repository.

With EDN, repositories are automatically created when new projects are defined. The name of your repository is the same as the project's identifier. To determine the project identifier, simply look at the URL for your project. For THIS project, the URL is: https://designlab.eng.rpi.edu/edn/projects/capstone-support-dev/working and "capstone-support-dev" is the identifier. If it had one, this project's working repository would be found at: https://designlab.eng.rpi.edu/svn2/capstone-support-dev/working

For security control, your EDN username and password are used to access the repository for your project.

Repository Folder Structure

There is a generally accepted convention for the folder structure. For the Design Lab, repositories will have two top level folders (note that these are all lower case):
  • tags - where archives are created ONLY by the Project Engineer after the end of each semester
  • working - where the current semester's work takes place

This initial folder structure is created by your Project Engineer at the start of a project. Future teams will then use that existing folder structure.

The working Folder

The concept of a "working" folder is that it is there for the entire life of a project. Whether the current team happens to need every file or not. It does NOT represent the currently semester's "working" folder. Some things that are clearly historical only, like background memos can be deleted after they are 'tagged'. Other things like the posters and reports are simply overwritten each semester with the latest and greatest since they too have already been tagged.

Working Folder Structure

Many of our projects run across multiple semesters with each new team broadly continuing the work of the previous team. Our projects in EDN are thus set up to support this. They are NOT set up on a semester by semester basis. The working folder will be where all of the project's (from all the semesters) active work will be saved. Your working folder is part of the technology transfer for your project.

PLEASE DO NOT CHANGE THE FOLDER STRUCTURE!

Within the working folder we use a "functionally" oriented folder structure:

    tags
    working
      ├ Background Information
      ├ CAD (mechanical & electrical)
      ├ Data
      ├ Engineering Analysis
      ├ Purchasing
      ├ Reports
      │   ├ Design Report + Poster
      │   └ Client Meetings
      ├ Software

The tags Folder

The tags folder is used to create "snapshots" of a project. Projects are tagged by the Project Engineer ONLY at the end of each semester after a thorough review. Students should NOT do the tagging.

Repository Usage Guidelines

  • All mechanical CAD models and drawings AND all electrical CAD (i.e. schematics) go to the CAD folder.
  • Purchasing folder
    • purchasing forms - scans or electronic version
    • Bill of Materials
  • Video Files
    • Please check with your PE BEFORE you place large video files on the repo.
  • Software folders
    • include all source code and “make” files or instructions on how to rebuild the program
    • For micro-controller types of programming be sure to include full instructions on how to obtain / load their development environment.
    • Do NOT commit virtual machine (VM) images! They are huge! Instead, fully describe how you built it in your project's wiki. Then future teams can rebuild it as needed. All of the key content (source code, data, etc.) on that VM should be coming from your repository.
  • DO include all documents in their “source” format not just a PDF of the output, ex: Solidworks / NX CAD models, Photoshop PSD files, etc. Future team(s) may want to reuse your information and/or edit it.
  • Do NOT zip/tar/7z/compress folders into the repository! It should reflect what you are actually working with (you're probably NOT working with zip files) and you do NOT really need to save space in the repository. By avoiding compressed files, others can simply checkout the desired folders and begin working on their contents.
  • For each directory, you should prepare a README file and include information to help future users utilize the stored files. See below.
  • Do NOT embed version information into folder or file names. For example have a folder called "Final". Do NOT have a folder called "Final - Spring 2011".
  • For teams that are using an existing Repository (from a previous semester's team(s) - review the current contents! They are there as your starting point.
    • Do not rename their folders or files with a semester name (see above!). Instead, use the existing folders.
    • DO NOT just delete things! Talk to your PE!
      • The Project Statement & Final Report/Poster will be called the same as what the previous team called it. Yours will then simply replace theirs. Please do not use a different name.
  • DO NOT name folders after the names of your team mates! Instead, be sure to use functional names. For example rather than calling a folder "Fred" because he happened to work on the CAD for a robot arm, call the folder "Robot Arm". Team members may work on more than one functional area - so naming the folders by person does not make any sense.
  • At the end of the semester, be sure to 'clean up' your Reports folder so that only your final version of the Statement of Work, Poster, and Design Report are there. Remove any drafts, temporary files, individual sections, commented copies, etc.

If in doubt, please ask your Project Engineer BEFORE you make organizational changes to an existing repo.
If you are not absolutely sure about how to proceed, ASK your Project Engineer before you make any changes!

Consult your faculty advisors on archiving any proprietary information obtained from the project Client.

README Files

Every folder should include a README file to help explain to the contents.

Subversion and Visual Studio Code
---

Attachments Below