StrivingLife presents ...

Last time, I played around with Subversion in order to determine just how Subversion worked.

This time I'm actually going to create a repository for a site to store the current version, and work through making a couple of updates.

Existing site structure

The site that I'll be working with is DoNotDenyMyUnicorn.com. It's a small, stable, site, that has just a few files. It's also relatively clean, with no previous versions floating about.

The directory for the site currently exists on another box, at C:\inetpub\wwwroot\donotdenymyunicorn\ and consists of 8 files in that directory.

1. index.html
2. main234x60.gif
3. print.css
4. robots.txt
5. screen.css
6. sitemap.xml
7. StrivingLifeGmail.png
8. (a Google-related file)

The new development structure

I won't be changing the structure of the site, but since I'll be moving the files to my Vista box, I'll have a slightly different structure.

First, I'll be storing the repository at B:\repos\DoNotDenyMyUnicorn\

The development files will be stored at B:\projects\DoNotDenyMyUnicorn\

My workflow

Since I'm the only one working on my sites, I'll be keeping things simple. I'll do all my development work in B:\projects\ and push files once they've been tested and commited to the repository.

Depending upon what issues I run into, this may change, but this is what I'm planning for now.

Creating the repository

The first thing to do is create the repository we'll be using. The location of the repository will be B:\repos\DoNotDenyMyUnicorn\ , so the first thing to do is make sure that the directory exists. In my case, I need to create the DoNotDenyMyUnicorn folder.

With that done, I can right-click on the DoNotDenyMyUnicorn folder and select TortoiseSVN > Create repository here... (type of Native filesystem, of course).

Creating the working/development directory

Now that I've got the repository created, it's time to put data into it.

As I said before, the development directory will be at B:\projects\DoNotDenyMyUnicorn\ .

Now I have a couple of options. I can either import my existing content into Subversion, or I can create a working copy, add my data, and commit it.

In this case I'm going to create a working copy, since that makes more sense to me.

So, I right-click on the DoNotDenyMyUnicorn directory in B:\repos\ and select SVN Checkout...

I'll confirm that the URL is correct (file:///B:/repos/DoNotDenyMyUnicorn) and browse to the Checkout directory of B:\projects\DoNotDenyMyUnicorn .

Pressing OK, I've now got revision 0 in my projects directory.

Next I'll grab the eight files from my XP machine, and copy them into B:\projects\DoNotDenyMyUnicorn\ .

I can now either 'Add...' each of the files I want under version control, or just right-click in/on the DoNotDenyMyUnicorn directory to select SVN Commit...

Depending upon whether I already added the files, I may need to select the files I want added, but since I want them all, a simple check of "Select / deselect all" selects the eight files.

I'll type a meaningful message ("Initial check-in.") and press OK.

This should add the 8 files, and create revision 1.

Making changes

Now there's just a few minor things that I want to change about the existing DoNotDenyMyUnicorn. I used Visual Studio 2008, but the editor doesn't really matter.

Once I've made my changes, I'll need to commit them to the repository.

This is as simple as either committing the changes by selecting, or by committing the entire project directory (DoNotDenyMyUnicorn, in B:\projects\) and letting SVN take care of the rest.

In my case I just had the one change.

Once I committed, I pushed the changed files up to my remote Windows server.

While doing so, I noticed that I had a favicon, that I didn't have on my devel site. Whoops.

It was easy enough to download that into my project directory, and add/commit that to the repository.

Conclusions

While this doesn't handle trunks, branches, tags, or any of that other fun stuff, for a simple Web site, as DoNotDenyMyUnicorn.com is, it's easy enough to move files into version control - much easier than I originally thought.

However, while we didn't talk about it, it's a very good idea to make sure that you have clean directories, without temp files, previous versions, and 'correct' directories. You can always exclude these from versioning, but a clean directory is a developer's favorite directory.

Next steps

My next steps are to move more of my sites into version control. Your next step should be to move one of your smaller sites, or test Subversion out.

I've flirted with source/version/revision control since September 2006 (with Subversion), but have never really dug in to actually do anthing with it. But now, that changes.

The basics of Subversion

The basics are that you have a repository to store files within. Files in the repository are not directly modified. Instead, you can check out a working copy of the files to work on. You can then check in (aka commit) your working files, at any time, so that they become a part of the repository. When you do this, a new revision is created. If multiple people are working on the same repository, you'll also need to update your working files and handle any conflicts.

Getting started with Subversion

I've already covered this in previous posts, for Windows installations.

• Subversion
• TortoiseSVN

These both cover Windows Vista installations, but an older guide exists for Windows XP.

TortoiseSVN isn't required, but I highly recommend it, and it's how I'll be working through this.

Creating a test repository 

The first thing to try is a 100% test repository. Again, this will be what keeps track of file versions.

Determine where you'll store your repositories. I have a second hard drive that I'll be using, so my repositories will be stored in B:\repos\ . Substitute your directory structure whenever you see this.

Next, create a new directory under B:\repos\, called repoTest.

Right click on the directory and select TortoiseSVN > Create repository here... (See this.)

When prompted, select Native filesystem (FSFS) for the repository type. (See this.)

With that, the repository is created.

Now that you've got a repository, it's time to check out a version you can work with.

Creating a working directory

Right-click on the repoTest directory and select SVN Checkout... (See this.)

You'll be prompted for the URL of the repository (which should be correct - in this case, file:///B:/repos/repotest) and a Checkout directory. This directory is where you'll store your working copy. I created a new directory B:\projects\repoTest\.

Leave all other options as they are and press OK to continue.

With that done, you should be shown a window stating that the checkout has finished.

If you now browse to your checkout directory (in my case, B:\projects\) you'll notice that the repoTest directory has a new icon - a green circle with a check.

Adding files to the working directory

Let's now create a text file called 'file number 1.txt' in the working directory. For now, leave the file blank.

Now go back up to the B:\projects\ directory and right-click on the repoTest folder. Select SVN Commit... (See this.)

Our new file is displayed in the lower half of the window that appears. Check the box next to the file name. Next, enter a meaningful message in the first text box. For example, "First check-in."  (See this.)

Press OK to continue.

A new window will appear showing that our file has been added and sent. We're also given a revision number, in this case, 1. (See this.)

Checking out another copy 

Now let's go back to our repository and checkout another copy.

This simulates another user working on our repository.

Once again, we can browse to B:\repos\ , right-click on our repoTest directory, and select SVN Checkout... Or, we can also select TortoiseSVN > Repo-browser . This browser enables you to see all the files in the repository, as well as additional details, like revision. (See this.)

If you right-click on the repository, you can select Checkout...

Either way you checkout the repository, do so to a new folder, such as B:\projects\repoTest2\ . (See this.) Press OK.

This checks out all files currently committed to the repository. So, when we browse to our new working directory, we'll see 'file number 1.txt' .

Where we're at 

Right now we've got a single repository and two working directories. This is similar to what one might see if two individuals are working on a project.

So, Lisa is B:\projects\repoTest\ and Trish is B:\projects\repoTest2\

Let's treat these imaginary users as human beings, and call them by there names from here on out.

Lisa adds new files

Switch to Lisa's repository at B:\projects\repoTest\ . Let's say she creates two new files, called "file number 2.txt" and "file number 3.txt" in this directory.

She also adds some text to file number 1, such as "Lisa has made a modification to this file."

When she modifies file number 1, note that it now has a different icon, as the file has changed.

Now we assume that she wants these to be a part of the repository, so in order to get them in there, she'd have to commit these changes.

Select both of the new files and select TortoiseSVN > Add...

In the prompt that appears, verify both checkboxes next to the file names are selected, and press OK. You'll then be told that both files are added.

You may have to refresh Explorer, but when you do so, you'll notice that the two new files have new icons - little blue plus signs.

Right-click in the repoTest directory, or on the repoTest folder, and select SVN Commit...

This time you'll see that you've modified one file and added two others. Make sure you put in a message, such as "Lisa updated file 1 and created files 2 and 3." You may note that when you type file, you've got the option to auto-complete with the file names. Pretty nice, eh? (See this.)

Go ahead and press OK, verify it completes, and press OK again. (See this.)

What about Trish?

Now Lisa is up to date with the repository, since she's the only one making changes. But what about Trish?

Let's switch to Trish's directory, B:\projects\repoTest2\ . She still just has file number 1.txt and it's still empty.

Let's go ahead and open her version of file number 1.txt and make a change. For example, add "Trish modified this file."

Right-click on the repoTest2 directory, or within it, and select SVN Commit... Make sure you enter a message!

If you try to commit, the commit will fail. Unfortunately, Trish's version is out of date (it says so). (See this.)

Getting Trish up-to-date 

We have a couple of options for getting Trish up-to-date. The first is to right-click on 'file number 1.txt' and select TortoiseSVN > Check for modifications. We'll see that Trish's version has been modified, and by double-clicking, can see what modifications took place.

However, that's what was modified from the version she checked out.

Press the Check repository button and you'll see an even newer version, the version Lisa checked out.

If we now double-click on the file we'll see Lisa's changes compared with our changes.

So now that we've got a conflict, what do we do?

Let's get an updated version of this file by right-clicking on the file and selecting SVN Update.

When we do so, we'll be told that a conflict exists, and will have a couple of files created in our working directory - 'file number 1.txt.mine,' 'file number 1.txt.r1,' and 'file number 1.txt.r2.' In addition, 'file number 1.txt' wll have a small warning icon.

Right-click on this file and select TortoiseSVN > Edit conflicts.

From within TortoiseMerge, we can right click on either of the differences and select a couple of options.

1. Use a specific text block from one file or another.
2. Use the whole file from one or another.
3. Put our text before/after their text.

The merged/final version will display in the bottom half of the window.

For now, let's go ahead and put Lisa's text before Trish's text.

Right click on the changed block from 'mine' and select 'Use text block from "theirs" before "mine."

In the merged version, you'll see Lisa's text before Trish's. Close out of TortoiseMerge and save your changes when prompted, or press the save icon, or select File > Save.

Trish's working copy has now been modified with the updated text, however the file still is in conflict.

Right-click on the file again and select TortoiseSVN > Resolved... Verify that 'file number 1.txt' is checked, and press OK.

Once you've done so, the extra files are removed from the directory. You'll now need to commit the file back into the repository. Now that the base copy is the same revision, the commit will complete.

What Trish should have done

However, there's still an issue with Trish's copy of the repository. She has no file 2 or 3.

What Trish really needs to do is update her copy. She can do so by selecting SVN Update, after right-clicking on/in the repoTest2 folder.

This will allow her to get all the updates that have happened since she first grabbed a copy.

She can also, from this window, see a log (by pressing "Show log...") of revisions, with messages.

Workflow with more than one developer 

Therefore, based upon this, it's a very good idea to make sure you're pulling updates from the repository on a regular basis.

While there may indeed be times when you don't want to do this, this will allow you to see what other developers have been working on.

She can also use a number of menu items to check on the repository without making commits. The log (Show log), repository browser (Repo-browser), and modifications (Check for modifications) can all be accessed at the directory or file level.

In the case shown below, Lisa has made two additional revisions since Trish last checked files out, including adding two new files and modifying two that Trish already has.

If Trish hasn't made any changes, it's easy enough to SVN Update and get everything she needs. If she didn't modify any files that have changed, then she won't have to handle any merging of changes. If she has, then she'll just have to handle the conflict, which can involve just ignoring it by using her version (Mine), if she's actually got the version that should be used.

Deleting our working directories

At this point we've covered what we need to cover for working with Subversion, using a test repository, and two working directories.

We can clean-up by deleting the B:\projects\repoTest\ and B:\projects\repoTest2\ directories.

Since our repository still exists, we can still get a working copy of the repository. However, if we delete the repository directory, B:\repos\repoTest\, our repository is gone.

Since we don't need it anymore, go ahead and delete this directory.

To conclude ...

Probably the best way to start with Subversion is to actually work on a dummy repository, as I've done above.

Next time

Next time I'll move an existing Web project into Subversion, since it's definitely time.

Questions, comments, concerns, definitely appreciated.

As it promises, Steve Krug's Don't Make Me Think: 2nd Edition, is a quick, but extremely usable, guide to Web usability and design. The book took me less than a day to read (less than 3 hours total over the days of September 26 and 27, of 2007), but has become, in my mind, a requirement for even beginners (like myself) of Web design. Since everyone who develops for the Web should have some idea of design and usability, this book should really be a mandatory requirement for said work.

In short, there's no reason not to read this book if you're developing for the Web (writing content, programming, etcetera), or working with a team that does so.

Notes on the book

The following are notes that I took while reading the book. They are broken up by chapter. These notes will not replace a reading of the book.

Chapter 1

• Eliminate question marks - "what does this do?" ...
• use common language
• keep things obvious
  

Chapter 2

• satisficing - first, best, option
  • guessing
  • back button most used browser feature

Chapter 3

• billboard design
• clear visual hierarchy
  • size, grouping, nesting
    
• use conventions
• clearly define page areas
• make clickable areas obvious
• minimize noise
  • busyness
  • background noise
  • everything is noise until proven otherwise
    
• replace text with a foreign language - does it still make sense (where things are)?
  

Chapter 5

• get rid of happy-talk - they're not going to read it, but they may think they have to ... (but they still won't read it)
• kill instructions 

Chapter 6

• navigation = getting from one place to another = figuring out where you are
  
• navigation reveals content
• presistent navigation - comfort for user; it'll be here, but it may change
• simpler navigation for forms and the like (where they need to perform a specific action)
• common elements; home, search, sections (nav), utilities (help use site: about us, contact, help, site map), site id/logo, title, indication of where you are
• home page != sub pages
• let people filter results (simple search) - more useful at that point (instead of before you even search)
• you need to know navigation from top-level to bottom-most level (id est, don't stop mocking up at the second or third level, keep going as necessary)
• every page needs aname - largest text
• visual cues of where you are can't be subtle; maybe two things, not just one
• breadcrumbs were an oddity - not a substitute for two levels of main nav
  • move them out of page - don't let them conflict with primary nav
    
• tabs are self-evident, like the Recycle Bin on computes to delete files
  • connect w/ secondary nav (like real life)
    • have one tab selected by default
      
• don't rely on color as the only cue
• 'trunk' test: look at a page from a distance, or with nonsense text
  • what site am I on?
  • what page?
  • what/where are the major sections?
  • options at this level?
  • where am I in scheme of things?
  • search/find?
    

Chapter 7 (home pages)

• common elements
  • site identity/mission
  • site hierarchy
  • search
  • teaser
  • timely content
  • deals
  • shortcuts
  • registration
• show me what I'm looking for (and what I'm not looking for)
  
• show me where to start
• establish credibility and trust
• must appeal to all visitors
• ?s: what is this?, what can I do here? what do they have here? why should I be here and not elsewhere? where do I start?
• tagline and brief, blocked, welcome blurb
  • tagline = value proposition (like 'the single best source for facts on the net')
    
• max of four features (to point out)
• should be able to answer where to start to search, browse, sample (the best)
• nav layout changes are oaky, but don't change the order (home page vs. sub-pages)
  

Chapter 8

• there is no average user
• there is no average user :D
• Web teams don't argue about big things (usually), just the minor issues (and these may not have right answers)
• testing is a good thing - get people to use proposed idea(s) and see how it really functions 

Chapter 9

• focus groups vs. usability testing
  • focus groups = group; wants, needs, likes > marketing; do it early, not late in the game (do it before you start designing)
    
  • usability testing = individual, task based; whether site works
    
• if people are getting lost, don't add more text - remove (distractions/noise) 

Chapter 10

• keep photos/figures in print-friendly pages, but don't include nav, ...
  

Chapter 11

• easy accessibility (first steps)
  • add alt tags to images
  • use labels in forms
  • skip to main content link (before any other content)
  • make all content accessible by keyboard
  • don't use JS without a good reason