Quick Reference

• ​list of cloneable repositories
  • ​bmidev repository

todo: explain ​Mercurial setup: One central repo or several?

Getting Started on Windows

Dan tested these instructions for getting TortoiseHG set up with Arvinder:

1. Visit the ​Mercurial downloads page and install TortoiseHG for Windows 32bit
   (current version is 2010-06-01: TortoiseHg 1.0.4 (with Mercurial 1.5.4)).
2. To get the shell integration running, log out and log in
   (I'm not sure that's essential... there's a start menu option that seemed to do the same thing for Dan... but logging out/in is what the ​documentation suggests).
3. Visited the ​web view of the bmidev repository (visit ​http://bmi-work.kumc.edu/changes/ and choose bmidev) and copy the address from there
   (Dan's rule #1: never type URLs anywhere but into your web browser; always copy/paste).
4. To make a local clone of that repository, as the docs say: From the explorer context menu select TortoiseHg... ‣ Clone a repository . Then paste the address of the bmidev repository as the source path and hit clone. The result is a bmidev folder on the desktop that has a local repository (.hg) plus a checked out copy of the current version.
   
5. Configured your username using the

   Donald Duck <donaldduck@example.net>
   

   convention as shown in the ​TortoiseHg tutorial/quick-start .
6. Make a trivial change (e.g. add your name to the list of developers in source:README.rst) and commit it to your local repository, describing that change. (see ​3.5 Commit for details).
7. Pushed to the server (see ​4.7.1 Sync Bar), and verify that you can see the change in the ​web view (and/or the trac timeline).

If you can see your change in the ​web, then you're all set. You can make more substantial changes similarly.

Good Commit Messages

Note that the 1st line of a commit message shows up in the trac timeline and such, so it should serve as a summary of the whole change. A reference to relevant ticket or tickets (#n, #m) is handy; on the other hand, don't assume people reading our code and commit messages have access to our tickets.

The ​AbiWord guidelines have more on good commit messages:

A good commit message:

• Has a short description as its first line, followed by a blank line
• Describes the changes and rationale, at a high level
• Mentions any bugs ("Fixes bug#999999") fixed by the included changes.
• Offers a brief acknowledgement to other developers who contributed substantially to the patch, debugging process, etc.

Reviewing the actual diffs as you write the commit message is a good habit to establish.

1. Ensure the commit message corresponds to the changes
2. Ensure the changes form a coherent unit,
   • or break into smaller commits
3. Think about whether your changes are adequately tested
4. Avoid checking in temporary kludges.

Push aborts because someone else got there first

If you see:

abort: push creates new remote head 7e32beb91d49!
(you should pull and merge or use push -f to force)

Then someone else has pushed a change since you last pulled and updated. You'll need to ​merge, e.g. using "Merge with local..." from the ​revision context menu in tortoisehg.

As this can get a bit fiddly, don't hesitate to get a more experienced developer involved.

Background and Further Reading

​Hg Init: a Mercurial tutorial by Joel Spolsky introduces version control with hg/mercurial this way:

Mercurial is a version control system . Developers use it to manage source code. It serves two important purposes:

1. It keeps track of every old version of every file
2. It can merge different versions of your code, so that teammates can work independently on the code and then merge their changes

Without Mercurial, you could try to keep old versions just by making a lot of copies of the directory containing all your code:

This is tedious, takes up a lot of disk space, and confusing. Using version control is a better way to do this.

It goes on to say:

Most people work with Mercurial through the command line, which works on Windows, Unix, and Mac.

But we can take advantage of ​TortoiseHG, which integrates mercurial with Windows. The ​TortoiseHG documentation has plenty of details on each feature, but it somewhat assumes that you know why you would want each feature. Joel gives a much better big-picture view. There's a ​mercurial book online, but Joel's tutorial is a much quicker read.

Elephant Never Forgets, World-wide Collaboration

Try to review each change and consider that the whole world can see it once it's pushed. Sensitive info (e.g. passwords) that get into the version control system is a pain to get out. Version control systems, by design, never forget anything. You can make a change to delete a file (see ​Fixing Goofs), but the repository keeps the previous state where the file existed. In extreme circumstances, parts of the history can be really deleted (see ​I committed a change containing nuclear launch codes, how do I delete it permanently? ), but it has a huge ripple effect.

SQL Formatting Conventions

When UsingVersionControl, formatting conventions become important.

Dan suggests attachment:sql_like_py.xml​​ for sqldeveloper preference.

​SQL Statement indentation good practice on Stack Overflow does pick a winner but doesn't really show that there's a strong community sense of best practice.

​sqlparse has an online SQL formatter.

SSIS

UsingVersionControl for ​SSIS in CDR Architecture? (#891) looks challenging:

The SSIS package contains both the executable blocks and the formatting for it, making it completely unreadable from plain text perspective, and making it impossible to understand what has change from a diff of the file. -- ​Ayende Rahien 15 Jul 2007

Java and Mercurial

todo: see JavaDevTools re mercurial eclipse stuff

Using ssh repositories from Windows clients

One UnderTheHood note: the shared repository is writeable by anyone with access to the internal network (ticket #4). As Joel puts it in ​Setting up for a Team:

Needless to say, this is rather unsafe, but if you’re on a nice protected LAN at work and there’s a good firewall and you trust everybody on your LAN, this is reasonably OK. Otherwise, you’ll want to read the advanced chapters on security.

​Accessing Ssh Repositories From Windows in the Mercurial wiki is one solution. Note the instructions for using passphrase-locked SSH keys.

For audit purposes, the md5sum of the installer from the ​putty downloads:

46f0615d61d9dad673cc07279ac43ed1  putty-0.60-installer.exe

The CRIS servers have more restricted network access, so we're looking into UsingSecureShell (#93).