Version control 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

-- ​Joel Spolsky's intro to version control with Mercurial

Note: We started as a mercurial shop in 2010, but we transitioned HeronLoad to git in 2016 and we're increasingly a git shop.

Getting Started and Tools

HeronLoadDev with git

• ​heron on github
  • ​git for windows
  • ​gitkraken - The most popular Git GUI for Windows, Mac AND Linux
  • ​It's Magit! A Git Porcelain inside Emacs.
    (​6 min Magit Basics video, ​20 min, ​online book)
  • git clone git://bmi-work.kumc.edu/heron-exclude-git (#3977)
  • Sqldeveloper support for git: ​SQL Developer’s Interface for GIT: Interacting with a GitHub Repository Part 2 April 16, 2014 by gbalda

HeronAdminDev with mercurial

• Windows, linux GUI: ​TortoiseHg
• repository URL: ​http://bmi-work.kumc.edu/changes/raven-j
  • nice web view in trac: source:raven-j
  • ​original list of cloneable hg repositories

The ​TortoiseHG documentation has plenty of details on each feature, but it somewhat assumes that you know why you would want each feature. ​Joel Spolsky's intro to version control with Mercurial gives a much better big-picture view. There's a ​mercurial book online, but Joel's tutorial is a much quicker read.

RStudio and git for reproducible science

• ​Version Control with Git and SVN – RStudio Support
  • ​15 minute video
  • example: ​https://github.com/kumc-bmi/bc_qa
    • Steve's fork: ​https://github.com/pmean/bc_qa

Administration

The git server process is called git-daemon. Start and stop it as usual (e.g. ticket:5031#comment:1). See ticket:4724#comment:5 to resolve errno=Connection refused.

Best Practices

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

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.

Elephant Never Forgets, World-wide Collaboration

It's important to:

• Keep patient data and other sensitive information out of version control work directories.
• Review each change and consider that the whole world can see it once it's pushed.
  • Take care with diff summaries in github, bitbucket where new files are summarized with just the filename.

Sensitive info (e.g. passwords, patient information) 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.

See also GroupOnly/TracPub.

Public Repositories

Take special care with public repositories. For example, put something like this in .git/hooks/pre-commit to prevent committing phone numbers:

• attachment:no-phone.sh
• attachment:pre-commit (python, for Windows)

SQL Formatting Conventions

When UsingVersionControl, formatting conventions become important.

Dan is working on ​SQL formatting conventions in GROUSE including sqldeveloper configuration.

​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.

Migrating from Mercurial to Git

• #3977: Move the HERON dev process to use git
  • milestone:aws-org-git
• ​gitconfig in sjl's dotfiles has nice hg-to-git aliases

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.

Getting Started with Hg on Windows

1. To avoid triggering an SSL: UNSUPPORTED PROTOCOL error while cloning a repository, go to File > Settings > Edit File (button in the top right of the settings window) and paste the following in the text editor that appears:

   [hostsecurity]
   bmi-work.kumc.edu:minimumprotocol = tls1.0
   

1. Configured your username using the

   Donald Duck <donaldduck@example.net>
   

   convention as shown in the ​TortoiseHg tutorial/quick-start .
2. 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).
3. 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.

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).