Kiln Documentation

Licensed Version: 2.9.60

Hosted Version: 2.9.52

  1. What are the system requirements for Kiln?
    1. How do I install Kiln 2.x?
      1. How do I uninstall Kiln?
    2. How do I enable and view logging in Kiln 2?
    3. How do I configure Kiln for my server?
    4. Can I have a different number of licenses for FogBugz and Kiln?
    5. How do I configure FogBugz and Kiln to require SSL (https)?
  2. I’ve got FogBugz On Demand already, how do I add Kiln to my On Demand account?
    1. I’ve got Kiln On Demand already, how do I add FogBugz to my On Demand account?
    2. How do I link FogBugz cases to Kiln reviews and vice-versa?
    3. How do I know which bugs have been fixed between builds?
    4. How do I know where my fogbugz case has been fixed?
    5. What exactly do Project and Repository permission levels mean?
    6. Is there a way to alias a URL to a repository?
    7. In Kiln 2, what’s the new API like?
    8. Offsite backups
    9. Does Kiln support web hooks?
      1. How do I test Kiln’s Web Hooks?
      2. Can I use commit hooks to reject malformed commits?
      3. Best Practice: Generating build numbers
        1. What are Access Tokens? Do they let me avoid using up a license on my continuous integration server?
    10. Un-Deleting Repositories
    11. Best Practice: Generating build numbers
    12. How can I strip changesets from the central repository in Kiln?
    13. Can I undo converting a branch repository to a central repository?
    14. How do I keep Kiln from showing a file in a diff?
  3. How can I successfully convert my repository to Mercurial?
    1. How do I import my files into Kiln from Visual Source Safe (VSS)?
    2. How to import a subversion repos with active branches
    3. Importing a subversion repository on a Mac
    4. Import git repository into Mercury/KILN
    5. How do I get a log of the Kiln Repository Import?
    6. Selectively converting SVN branches
    7. What’s the best way to adapt our existing Subversion project layout to Mercurial using Kiln’s Project > Repo Group > Repo heirarchy?
  4. I have absolutely no clue how to get started with Mercurial. Can you please help me?
    1. How do I use TortoiseHg? I have no idea.
    2. Doc on how to best configure/use TortoiseHG with Kiln?
    3. Mercurial Branches and Kiln’s Forks
    4. Kiln Branch and Merge How-To
  5. Where can I find the Kiln Client and Tools?
    1. What is the Kiln Client?
      1. What is the difference between TortoiseHg and KilnClient?
    2. What do the Kiln extensions do?
    3. I heard Kiln added kbfiles support in 2.0! What does that mean?
      1. How do you use kbfiles?
    4. How do I use the Mercurial LargeFiles Extension?
    5. How do I clear kilnauth cookies?
    6. How do I use kilnauth from Cygwin?
    7. How can I install Kiln’s Mercurial extensions manually?
  6. What do you do to make sure my source code is safe?
  7. How do I start a code review?
    1. What is the best workflow for performing a series of code reviews?
    2. How do I add a commit to an existing code review?
    3. What’s with the new review system?
  8. Kiln and Visual Studio 2008
  9. How do I use the Electric DAG?
  10. Kiln 2.0 Search
  11. Kiln 2.0: Command Line Path Guessing
  12. What’s new in Kiln 2.4.105?
  13. How do I view the Annotation of a file in Kiln?
  14. How can I find out which version of Kiln I’m running?
  15. Do I own both {my}.fogbugz.com and {my}.kilnhg.com?
  16. How can I easily let guests see my code?
  17. Should I use more than one repository?
  18. Can I control Kiln’s display of diffs and files?

What are the system requirements for Kiln?

Kiln currently supports:

  • Windows 2003 Server SP2 or later, Windows 2008 Server, and Windows 2008 Server R2 (sorry; Itanium not supported)
  • Microsoft SQL Server (2005, 2008, 2008 Express, or 2012)
    • Full-Text Search is required for Kiln 2.8 and earlier.
    • Note that the Express edition has a 10 gig database size limit and 1 gig RAM limit
  • Microsoft IIS 6.0 and later
  • 2 GB RAM Minimum; 8 GB RAM Recommended
  • Running Kiln or the FogBugz/Kiln bundle in a virtual machine is not generally recommended. Since Kiln is an extremely disk-heavy application, you may experience performance degradation. Please see Can I run Kiln in a VM / Virtual Machine? if you are considering running Kiln in a virtual environment.
  • The KilnRepositories folder requires a physical disk (not a network share)

On the client side, please make sure you're using one of our supported browsers.

Note that Kiln cannot currently be installed on a Primary Domain Controller. Also note that Kiln must be installed on the same server as FogBugz.

See also this posting on the FogBugz Knowledge Exchange




How do I install Kiln 2.x?

Overview

Every licensed Kiln customer can download an installer which has a wizard to help guide you through the various steps needed to get Kiln running on your server. For the vast majority of customers, the defaults we've selected will be your best bet for a successful installation.

This document has a few sections:

  1. System Requirements
  2. Before you begin
  3. Installer Walk-through
  4. Advanced Instructions
1. System Requirements

Kiln supports a narrow range of systems at the moment. Make sure you're installing on a system that meets these requirements because we can't support anything else right now (sorry!).

Operating System(s)

Windows 2003 and 2008 server

Database Server(s)

Microsoft SQL Server 2005, 2008, 2008 Express*, or 2012. (Full Text Search is required for Kiln 2.8 and earlier.)

* Note that the Express edition has a 10 gig database size limit and 1 gig RAM limit

Physical vs. Virtual Machine

Running Kiln or the FogBugz/Kiln bundle in a virtual machine is not generally recommended. Since Kiln is an extremely disk-heavy application, you may experience performance degradation. Please see Can I run Kiln in a VM / Virtual Machine? if you are considering running Kiln in a virtual environment.

2. Before You Begin

Just a few things that we wanted to let you know before you begin the installation process:

  1. The server may require a restart to finish. If it does, just restart the installer and it will pick up right where it left off. If possible, it's best to schedule the installation of Kiln during off-hours if you are installing on a production machine.

  2. Kiln requires some FogBugz components. We actually launch a seriously trimmed down FogBugz installer during the setup process. Don't worry; This is totally normal :)

  3. You need to run the installer as a SQL and Windows administrator. We make changes to Windows and SQL Server that require administrator access. If your SQL Server is on another computer, you need to take extra care to make sure your user has the right privileges.

  4. If you want Kiln and FogBugz to work together, they have to run on the same server. At least the front-end components do. It is possible to have your DB and Mercurial repositories elsewhere.

  5. Installation of Prerequisites requires internet access. If your server is missing any prerequisites, setup will download and install them for you. If your Kiln server does not have access to the public internet, please see this post.

3. Installer Walk-through
Welcome

The easy one. Just click Next because you've already got these instructions open (pat yourself on the back).

Prerequisites

If Kiln needs any supporting software installed beforehand, just click Install Prerequisites and it will launch Microsoft's Web Platform Installer to get everything installed. This varies depending on the state of your system. If you've asked the Kiln installer to install a SQL Express instance for you, this step can take a while. Go get yourself a cup of cocoa, and relax for a little while. If necessary, this may restart your server. Once it's restarted the Web Platform Installer will continue installing prerequisites. Once it is finished, you can restart the Kiln installer.

Settings

The settings page lets you specify where to install the three main components of Kiln.

Website

The Kiln website will be linked with a FogBugz install. You can select an existing FogBugz install, or have the Kiln installer create a new FogBugz installation. Kiln will be located at http://your.fogbugz.url/kiln. If you want fully integrated Kiln and FogBugz, they must be installed on the same server.

Database

Kiln uses SQL server to store meta data about your code and code reviews. Basically, it's what we use to make the Kiln web front end work. Your code isn't stored here. You can choose any SQL Server 2005/2008 or SQL Express 2008 instance. If you don't have one available, Kiln can install and configure a SQL Express instance for you during the Prerequisites step.

Storage Service

The Kiln storage service manages the Mercurial repositories that you create while using Kiln. We strongly recommend that you install the Storage Service on the same machine as the Kiln front end. It is slightly more secure, and it reduces complexity which makes managing your Kiln installation easier.

Installation

Once you've selected these settings, installation will begin. The installer will do the following:

  1. Install Kiln files
  2. Launch the Kiln Storage Service installer
  3. Launch the FogBugz installer to install/upgrade the FogBugz Base components
  4. Configure the Kiln website and database
  5. Launch Kiln in your default web browser to let you log on and install licenses
Kiln Storage Service Installer

This installer asks for some very basic information about where you want to install it, and where you want it to store your Mercurial repositories. Mercurial is very efficient about how it uses storage, but you will want to make sure you put your repository directory in a place with plenty of available disk space (10GB minimum, likely more).

Note: As of Kiln 2.9, the Kiln Storage Service's KilnRepositories folder may not be located on a network drive.

The FogBugz Installer

If you've ever installed FogBugz, you will recognize the installer and probably realize that it is seriously shortened. The only critical thing here is setting up the FogBugz user. The web components and system services for both Kiln and FogBugz will run as this user. It is also used to connect to the SQL database. If SQL Server is on a different machine, you will want to make this a domain user.

Login to Kiln, and enter your licenses

For the duration of the beta, a 100 user license will come pre-installed with Kiln. After that, this step will take you through the normal licenses installation procedure. If you already had FogBugz, you will need to log on to Kiln with a FogBugz administrator account and enter your Kiln licences on the Admin -> Licenses page. Otherwise, you will login with the default administrator account and enter your licenses.

4. Advanced Instructions

If you've gotten this far you've already mastered Windows permissions entanglement theory. That's not advanced enough for you?

Using Mixed-Mode authentication to connect to the Kiln database. You needed to run the installer as a user with administrator permissions on the database. After Kiln is installed, you can change the connection string in the web.config file to use a specific database user, rather than a Windows user. The database user will need to be an administrator for the Kiln database. Just replace Integrate Security=SSPI; with User Id=myUsername;Password=myPassword;. Once you've done this you can revoke permissions to the user that was setup by the installer (typically the FogBugz user).

This section will continue to be filled out as people try, and we work to support, more complex environments for Kiln.




How do I uninstall Kiln?

Currently, uninstall support is very basic.

First, uninstall the Kiln website by going to Add/Remove Programs in the control panel. Find the one titled "Kiln 1.0 (Or whichever version you have)" or "Licensed Kiln" and uninstall it.

If you are not keeping your FogBugz install, use Add/Remove Programs to uninstall it also. It is recommended that you do not remove the FogBugz user if you're planning to reinstall FogBugz and/or Kiln on the same machine.

That's all that you'll need to do to remove Kiln and should allow it to be reinstalled in the future if you choose to try it out again, but there will be some leftover stuff that you can clean up if you want to.

All versions

  • Delete the %APPDATA%\KilnInstaller directory on the account used to install Kiln
  • Delete the kiln database

Kiln 1.1 or earlier

  • Remove the registry keys at HKLM\Software\Fog Creek Software\Kiln and HKLM\Software\Wow6432Node\Fog Creek Software\Kiln
  • Uninstall Inno Setup and ISTool
  • Uninstall the Kiln Storage Service



How do I enable and view logging in Kiln 2?

Logging for the Kiln Storage Service is automatically enabled and is called errors.txt. It is located in the directory containing your repositories which you specified during the installation process (by default: C:\KilnRepositories\errors.txt).

Logging for the Kiln site in general needs to be enabled via the registry. You'll be adding these keys at HKLM\Software\Fog Creek Software\Kiln\Daemon or HKLM\Software\WOW6432Node\Fog Creek Software\Kiln\Daemon if you're 64-bit.

To enable, add a new String key named LogFile with a value of the path you want to logs to be stored in (e.g., C:\KilnRepositories\daemon.txt), then create a new String key named LogLevel with a value of info, critical, or debug depending on your needs.

Once you restart the Kiln Storage Service, logging will start. Log files don't roll over, however, so beware of how large these files may get if left unchecked!




How do I configure Kiln for my server?

Kiln On Demand

There are no configuration options for Kiln. We've set up everything for you. Move along. Nothing to see here.

Kiln for your Server

First, read Kiln's system requirements and installation instructions.

Running Kiln or the FogBugz/Kiln bundle in a virtual machine is not generally recommended. Since Kiln is an extremely disk-heavy application, you may experience performance degradation. Please see Can I run Kiln in a VM / Virtual Machine? if you are considering running Kiln in a virtual environment.

The only configuration setting you are likely to want change is the database connection string in the Web.config file. It should look like this:

<add name="KilnConnectionString" connectionString="Data Source=localhost;Initial Catalog=kiln;Persist Security Info=True;Integrated Security=SSPI;MultipleActiveResultSets=true;" providerName="System.Data.SqlClient" />

There are a few things you can change in the "connectionString" if you move the Kiln database or want to change the connection settings:

  • Data Source is the address of the SQL server
  • Initial Catalog is the name of the database
  • Integrated Security=SSPI; indicates that you want to use Windows authentication, and the same user that runs the Kiln web application to access the database
    • This can be replaced with "User Id=myUsername;Password=myPassword;" if you would prefer to use SQL Server authentication



Can I have a different number of licenses for FogBugz and Kiln?

No, you can't have a different number of users for FogBugz and Kiln. We took this into consideration when deciding on pricing, which is part of why we made the bundle discount so deep (80% off for Kiln On Demand, 50% off for Kiln on your server). Thus, you would need less than 20%/50% of your users to be developers before you hit the break-even point based on the standalone price. Think of it like sort of like MS Office, sure not everyone uses Powerpoint or Access, but since its so inexpensive to have all of them (relatively speaking), you don't hesitate to make use of them when appropriate.

Another thing to keep in mind, we've found it immensely useful for customer service and management to have visibility into what's going on in the code. It helps people understand the complexity of certain problems or features, and gives them some insight as to what is going in to fixing a bug that they've found. In other words, there's utility there for people working directly or indirectly with developers, not just directly with the code.

If it's a security issue, it is easy to configure strict permissions on everything in Kiln, so no need to be concerned there.




How do I configure FogBugz and Kiln to require SSL (https)?

Follow these steps to setup SSL for FogBugz in IIS, then update your web.config in C:\Program Files\Kiln\website\Kiln, so it knows the correct url for accessing FogBugz. Make sure to change http:// to https://

<add key="FogBugzUrlPrefixOverride" value="https://your/fogbugz/url" />



I’ve got FogBugz On Demand already, how do I add Kiln to my On Demand account?

This is actually really easy. Log into FogBugz as a site administrator and go to the Admin menu and choose Your On Demand Account. On that page, change the selection next to Your Plan to FogBugz & Kiln

Once you've confirmed the plan change, you're done! Kiln is now active. Navigating to Kiln is as simple as clicking the Kiln tab above the main navigation bar in FogBugz or your account page.

If you're an existing FogBugz customer who has never tried Kiln you will automatically get a free 45 day trial. At the end of the trial, you will have to opt-in to keep Kiln active. That means we will never charge your card without you explicitly telling us it's OK.

If you've already had a free trial of Kiln your plan change will be reflected on your next monthly statement and you will be charged the Bundle rate for your users, currently US$30 per user per month (volume discounts apply).

Note:

The Fog Creek Development bundle plan saves you a lot of money as compared to standalone Kiln and FogBugz accounts. The products work so well together that we wanted it to be a no-brainer to get both.




I’ve got Kiln On Demand already, how do I add FogBugz to my On Demand account?

This is actually really easy. There are a few ways that you can do this, but we recommend that you go to the Admin menu, and choose Your On Demand Account:

Your On Demand Account

Once there, you will see the Your Plan section. It should look like this:

Your Plan, Kiln Selected

To upgrade to the bundle, simply click the FogBugz & Kiln option on the right (you will be asked to confirm your selection, so don't worry).

Once you confirm the plan change, you're all done! FogBugz is now active. Navigating to FogBugz is as simple as clicking the FogBugz tab above the main navigation bar in Kiln or from your account page.

Note:

The Fog Creek Development bundle plan saves you a lot of money as compared to standalone Kiln and FogBugz accounts. The products work so well together that we wanted it to be a no-brainer to get both.




How do I link FogBugz cases to Kiln reviews and vice-versa?

NOTE: This post is only fully relevant to Kiln 2.7 and earlier. Kiln code reviews are no longer managed through FogBugz. For more information on the new Kiln code review system, check out this article: http://kiln.stackexchange.com/questions/4836/whats-changed-with-kilns-code-reviews

Just mention some variant of review 123, "case 123", "bug 123", or the like in your commit message, and Kiln will automatically associate it with the corresponding case in FogBugz. These forms are all completely identical, as far as Kiln is concerned; just choose whichever one gives you the best readability.

If the bug you mention is a review, then your changeset will automatically be added to the review if possible (i.e., it's in a related repository).

Cases associated with changesets in a review are also associated with any reviews that changeset is in automatically.

If you forget to link a changeset to a case at at commit time, Kiln allows you to associate cases with changesets after the fact. Simply click on the "Add Case" button when viewing the changeset you've just pushed.




How do I know which bugs have been fixed between builds?

Yes it can! Part of our new integration between Kiln and FogBugz is a FogBugz search axis which lets you specify two Tags from Kiln. Let's say you have two Changesets tagged Build_1.0.3 and Build_1.0.4 simply search for

tagrange:"Build_1.0.3..Build_1.0.4"

The result set will be all cases which have been completed between those two tags.

The exact workings of this axis are as follows. If you search for tagrange:"tagA..tagB" first we will find every repository that contain both tags. Then we return all cases such that every associated changeset is an ancestor of tagB and at least 1 changeset is not an ancestor of tagA. Another way to think of this is: Bugs with changesets after tagA with no changesets after tagB. This set of cases is the set of cases which were completed between the two tags.

There is a corresponding filter "kiln - completed between" which returns an identical result set.




How do I know where my fogbugz case has been fixed?

When viewing a case that's been associated with changesets, FogBugz will display a "View Checkins" link. The checkins popup, which appears when this link is clicked, has been completely revamped in Kiln 2.0. These changes have been made to help you find your checkins much more easily.

  1. Each changeset is only listed once even if it's in multiple repositories. If your changeset gets pushed to many repositories, this will significantly reduce the clutter.

  2. Each changeset is displayed alongside a list of every repository which contains it. This means that at a glance, you can see which changesets have been pulled where.

  3. On the bottom of the popup we dispay which repositories completely contain all changesets. This way you know which repositories contain the full fix, and which still need to pull.

  4. Lastly: the most powerful bit of information. If all of your checkins are contained within a central repository, we will tell you which tags contain all of the checkins. Informally this means the first tagged changesets in which your bug has been fixed. Formally this is the Least Common (tagged) Descendants of all checkins associated with the case.

This is just one of the new features which will hopefully make the integration between Kiln, FogBugz and your build process just that much tighter.

alt text




What exactly do Project and Repository permission levels mean?

Want do see a quick video demonstration of how permissions work? Check out our blog post on Control Who Can Access Your Code.


Kiln has a Project > Repository Group > Repository hierarchy.

Project admins are able to do everything in a Kiln project. That means they can clone and pull from repos, push to repos, create new central repos, access organize mode which allows for the creation, movement and modification of repositories and repository groups, delete repositories, configure project permissions and delete projects.

Repo admins can access repo settings page but can't can't do anything on the repository group/project level without the appropriate project level permissions.

It sounds like the best thing to do for your developers would be to give them modify permissions on the project in question. With the modify permissions they will be able to branch from this core repo, but will not be able to access any settings nor create other central repositories.

This is the primary Kiln Q&A site, but more information can be found at:

/Kiln/support.html




Is there a way to alias a URL to a repository?

Excellent question. Tremendously well-written. In Kiln 2, there is a new feature, Repository Aliases, that will let you do precisely that. In each project, the administrators can to create, update, and delete these aliases, which should simplify build scripts and the life of the resident build manager.

A quick fun guide to repository aliases

(Note: You must be a project administrator to participate in this quick fun guide.) Start by going to your Organize Projects page:

Organize Projects

Above the repositories, there exists the Manage repository aliases link!

New link OH MY GOODNESS

Click on it to bring up the Organize Aliases popup:

Organize Aliases popup WOW I SHOULD PAY MORE FOR KILN

Let's dramatically improve our build manager lives by adding a new alias for the legacy version of FogBugz 8.6 in this imaginary universe:

Adding a new alias MAYBE THIS IS TOO PERFECT?

Click Done. You should now see the alias show up inside the 8.6 repository link:

The alias link in action HOW IS THIS EVEN POSSIBLE

Clicking on the alias brings up a helpful information popup about it:

Alias Information popup SO INFORMATONATIVE

We can now use that URL in hg instead of the actual URL:

$> hg clone "http://localhost/FogBugz/Kiln/RepoAlias/Fog/legacy"
destination directory: legacy
requesting all changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
updating to branch default
1 files updated, 0 files merged, 0 files removed, 0 files unresolved

And, when 8-7 becomes the legacy repository, all you have to do as the build manager is go back to the Organize Aliases popup and change the alias to point to the 8-7 repository. No build script modifications necessary.

Use the extra time to sip on your piña colada. You deserve it.

All this, and more, in the exciting new Kiln 2 release.




In Kiln 2, what’s the new API like?

Sure, oddly well-informed stranger! API 1.0 will provide read/write operations to some basic Kiln objects: projects, repository groups, repositories, reviews, and people permissions. A new Kiln developers website will go live describing the API in its entirety rather than me boring you here. Take a look at the Kiln Developers website for more details!

The new API runs over HTTP and returns JSON objects. (Not XML, if you're coming from the FogBugz platform.) As always, this Stack Exchange will be the place to get Kiln development help. We're excited that the power of Mercurial features like hg log or hg diff will be one HTTP request away. And we hope to continue iterating on the API as we receive developer feedback, exposing more of Kiln's functionality through it as time goes on.

Some examples of what you can do with the new API:

  • TA a class of 300 students, each with their set of collaborative repositories with custom permissions that could be set up with a script.
  • Find true love, then lose it.
  • Be notified from your iPhone when someone assigns a review to you.
  • Rename, move, branch, and manage repositories from the command prompt.

So, in Kiln 2, you should be able to develop some basic applications based on Kiln from any programming language with an HTTP library, JSON parsing, and a good heart. We look forward to seeing what people do with it! (Good things, we hope.)




Offsite backups

Update by Fog Creek Support:

We have not tested any of the scripts mentioned with kbfiles or largefiles. Using these extensions causes certain files not to be present on your machine until you update to a given revision. If you use a filesystem copy of C:\KilnRepositories on your locally installed Kiln instance, you have a full backup. If you are using a script to hg pull your repos from a local or an On Demand site, please see the command here which updates to all revisions to make sure every version of a kbfile/largefile is present.


There are couple of options to create off-site backups of your repositories. Essentially the core concept is to run a script on a remote server, use the Kiln API to enumerate the repositories on the kiln server and then use simple hg clone / pull commands to get current copies of the repositories on the remote server.

There are a couple of user-written scripts that do just that. The first was written by Stefan Rusek and is available here, and the second was written by Nate Silva and can be found here.

These scripts are both pretty generic and might work perfectly for your needs without modification. Alternatively you could use them as a starting point and expand the scripts to suit your own environment.




Does Kiln support web hooks?

Yup! Kiln administrators can add web hooks as useful integration points between Kiln and any number of other services.

Just choose the URL Kiln should hit and which repositories should fire the hook. Then, every time these repositories receive a push, information about the push and its changesets will be POST'ed to the URL.

The data POST'ed is a JSON payload, and the data is accessible via the "payload" POST variable. So if you're in .NET land, you'd access the JSON payload like so:

string s = Request["payload"];

...and string s will contain a JSON string of the following format:

{
  "commits": [
    {
      "author": "Ben Kamens <ben@fogcreek.com>", 
      "branch": "default", 
      "id": "16265aef917cfe137e250c4f71a4a77ff4ad0974", 
      "message": "This thing is taking forever", 
      "revision": 14, 
      "timestamp": "3\/23\/2010 3:42:42 PM", 
      "url": "http:\/\/kamens.kilnhg.com\/Repo\/Personal\/Playground\/DNForever\/History\/16265aef917cfe137e250c4f71a4a77ff4ad0974",
      "tags": [
        "tip"
      ]
    }, 
    {
      "author": "Ben Kamens <ben@fogcreek.com>", 
      "branch": "default", 
      "id": "a077d19afed224dc7c46dc535d5f7e90546ed5bd", 
      "message": "This version is now shippable", 
      "revision": 15, 
      "timestamp": "3\/23\/2010 3:42:46 PM", 
      "url": "http:\/\/kamens.kilnhg.com\/Repo\/Personal\/Playground\/DNForever\/History\/a077d19afed224dc7c46dc535d5f7e90546ed5bd",
      "tags": []
    }
  ], 
  "pusher": {
    "email": "ben@fogcreek.com",
    "fullName": "Ben Kamens"
  },
  "repository": {
    "central": true,
    "description": "Picking up where the others left off", 
    "id": 1,
    "name": "DNForever", 
    "url": "http:\/\/kamens.kilnhg.com\/Repo\/Personal\/Playground\/DNForever"
  }
}

...which you can then parse and use however necessary in your continuous integration server or any piece of software that needs to know when Kiln receives a push.

The repository.id key is the repository's ixRepo, suitable for sending to the Kiln API.

Note that the timestamp for commits are in UTC.

Please keep in mind that this data will be sent regardless of your Kiln repository's permissions settings.

Here are some instructions for testing your web hook to make sure it's firing.




How do I test Kiln’s Web Hooks?

  1. Go to postbin.org (or the newer http://requestb.in/)
  2. Click "Make a postbin" to create a postbin for yourself
  3. Create a new Web Hook in Kiln that points to your postbin URL.
  4. Push some code to one of your Kiln repositories. Note that data about this push will be publicly available, so do not push anything sensitive.
  5. If everything worked properly, your postbin URL will now display all of the data sent from Kiln to postbin.org by the Web Hook, and it should look very similar to this example web hook data.



Can I use commit hooks to reject malformed commits?

On the client it is, see Chapter 10 of the Mercurial Book for docs that explain it reasonably well.




Best Practice: Generating build numbers

At Fog Creek, we use tags that match a regex to set the build number. For example, the current version of Kiln 2.0 that's on On Demand is generation 240, so there's a tag called Hosted_Kiln_240. Every time we cut a new build, we make a new tag, and the build scripts know to look for Hosted_Kiln_(\d+) to set the build number.

That works great for us. We only make a couple of builds per day, and we make lots and lots of commits. But if you had, say, a continuous integration system running, it'd be incredibly annoying; your commits would get drowned out by the new tags.

The "right" thing to do is to use the changeset numbers. I say "right" because it's the only thing that will be constant across all repositories. They just happen to be ugly.

Thankfully, if you want something that's a lot more readable and will work just fine (with some caveats), there are two solutions:

  1. If you're always building from the same repository, you can simply use Mercurial's revision number. Just remember that it's not constant across repositories, so if you cut builds for the same product from two different repos, you're in for a world of pain. Otherwise, though, you should be fine. When we first switched to Mercurial, Copilot used that scheme, and it served us well until we switched to a tag/regex-based solution.
  2. If you want something similar, but more informative and (slightly) more resilient to you switching repositories, you can use Mercurial's latesttag and latesttagdistance template tags. These tags will tell you what the most recent tag was in the repository, and how many changesets sit between the changeset in question and that tag.

    For example, from your project, try running hg parents --template '{latesttag}+{latesttagdistance}\n'. On my system, for example, that gives back Hosted_Kiln_240+11, meaning that my team made 11 new changesets since we cut version 240. If you were using more traditional version numbers for your tags, it'd be pretty reasonable to just grab {latesttag}.{latesttagdistance} to get a traditional <major>.<minor>.<bugfix>.<build>-style version number.

As I said, both of these methods are "bad" in the sense that they are repository-dependent. If you really need cross-repository build consistency, you probably really do want to suck it up and go the tagging route. But, as long as you keep the caveats in mind, this should provide you clean, easy-to-use build numbers that'll still reliably identify what changesets ended up in the build.




What are Access Tokens? Do they let me avoid using up a license on my continuous integration server?

There sure is! Starting in Kiln 2.5.170, a new feature, called Access Tokens, allows CI systems to work with Kiln, without using up a Kiln license. Access Tokens arent full-fledged Kiln accounts; they only allow cloning and pulling from Kiln repositories, optionally pushing to them, and working with the JSON API. They also run in two permissions modes: global, read-only access, which allows read-only access to the API and repositories (i.e., cloning and pulling); and global write access, which allows pushing to all repositories, plus a limited ability to edit some Kiln objects via the API.

The Access Tokens configuration screen can be access via the Administration menu

Making access tokens is simple. To create one, just go to the Access Tokens page, click Create New Access Token, give it a name, and presto, youre done. You can change the name at any point just by clicking on the description, giving it a new description, and saving your changes. You can also toggle whether the token is read-only or read and write via the same editing mode.

You can edit tokens just by clicking on them.

So, how do you use Access Tokens? Its easy as pie. When interacting with Kiln via Mercurial, simply supply the token ID with any password (the password is ignored). When interacting with the API, simply use the access token as your Kiln token.

Thats it. Everything else works as normal.

On a build server, you can put the token in the hgrc file inside a repo's .hg folder, or in the build user's Mercurial.ini file.

[auth]
kiln.prefix = path.to.kiln.com
kiln.username =  9f5d3162-1678-43d9-ae70-06bc4def15b9
kiln.password = anypassword



Un-Deleting Repositories

Click Admin -> Project -> Edit (next to the project with the deleted repo)

Then click "Show deleted repositories" Then you can undelete the repository.




Best Practice: Generating build numbers

At Fog Creek, we use tags that match a regex to set the build number. For example, the current version of Kiln 2.0 that's on On Demand is generation 240, so there's a tag called Hosted_Kiln_240. Every time we cut a new build, we make a new tag, and the build scripts know to look for Hosted_Kiln_(\d+) to set the build number.

That works great for us. We only make a couple of builds per day, and we make lots and lots of commits. But if you had, say, a continuous integration system running, it'd be incredibly annoying; your commits would get drowned out by the new tags.

The "right" thing to do is to use the changeset numbers. I say "right" because it's the only thing that will be constant across all repositories. They just happen to be ugly.

Thankfully, if you want something that's a lot more readable and will work just fine (with some caveats), there are two solutions:

  1. If you're always building from the same repository, you can simply use Mercurial's revision number. Just remember that it's not constant across repositories, so if you cut builds for the same product from two different repos, you're in for a world of pain. Otherwise, though, you should be fine. When we first switched to Mercurial, Copilot used that scheme, and it served us well until we switched to a tag/regex-based solution.
  2. If you want something similar, but more informative and (slightly) more resilient to you switching repositories, you can use Mercurial's latesttag and latesttagdistance template tags. These tags will tell you what the most recent tag was in the repository, and how many changesets sit between the changeset in question and that tag.

    For example, from your project, try running hg parents --template '{latesttag}+{latesttagdistance}\n'. On my system, for example, that gives back Hosted_Kiln_240+11, meaning that my team made 11 new changesets since we cut version 240. If you were using more traditional version numbers for your tags, it'd be pretty reasonable to just grab {latesttag}.{latesttagdistance} to get a traditional <major>.<minor>.<bugfix>.<build>-style version number.

As I said, both of these methods are "bad" in the sense that they are repository-dependent. If you really need cross-repository build consistency, you probably really do want to suck it up and go the tagging route. But, as long as you keep the caveats in mind, this should provide you clean, easy-to-use build numbers that'll still reliably identify what changesets ended up in the build.




How can I strip changesets from the central repository in Kiln?

One of Kiln 2.0's more hidden features is the ability to strip changesets from central repositories directly from Kiln. This could come in handy if, say, you misspelled a commit message, accidentally pushed it to Kiln and now want to change it; or if you accidentally added a file that contained patented code/personal information/other bad things. Strip allows you to rewrite the history of a repository to make it as if whatever you did never even happened.

Unfortunately, being able to strip your local repositories is only part of the answer - if the changeset was pushed to Kiln, it will simply reappear in your local repository the next time you pull. Kiln 2.0 allows you to strip changesets from a Kiln repository through the web interface. A backup will be created automatically as a branch of the stripped repository.

  1. Pick a changeset. That changeset and its descendants will be removed from the repository - including merges, so be aware that you could create multiple heads. Copy the ID of that changeset to the clipboard.
  2. Go to the repository's settings page.
  3. Expand the "Strip Changesets..." section, and paste the changeset ID from step 1 into the text box. Click "Strip".
  4. The changesets that will be stripped are highlighted in red - make sure that the changesets you intend to strip are highlighted, and no others. When ready, click "Strip".
  5. You will be brought to a waiting page while the stripping operation takes place.

While we provide this functionality as a convenience tool, we encourage you to use it only in dire circumstances. As this post points out, stripping from the main Kiln repository can have unexpected consequences if others had pulled the changesets before you stripped them. (An alternative is to use 'hg backout'.) It is also worth noting that the stripping operation on the website can take quite a while - have patience, and discourage other contributors from pushing or pulling during the strip.




Can I undo converting a branch repository to a central repository?

No, there are a number of implications of this that we wanted to avoid.

The easiest way to achieve the same result is to rename the current repo, make a branch from it with the original name, reparent that branch to the original parent, and delete the extra central repo.




How do I keep Kiln from showing a file in a diff?

You sure can! As of Kiln 2.4, simply check in a file called .kilnignore in the root of your repository, using exactly the same syntax as a .hgignore file. Any files you specify there will be ignored when Kiln renders diffs. But don't worry: they'll be version tracked and stored just like any other file. You'll only be changing how they're shown in Kiln. So if you later change your mind, just remove the banned file from your .kilnignore file, and it'll show up in diffs again, just as if nothing has changed.

So for example, let's say that my IDE makes solution files called LotsOChurn.solution, that I want to ignore. I also want to ignore all of my minified JavaScript, which I always make sure ends with the extension .min.js. In that case, to tell Kiln to ignore those files, I'd just put the following in my .kilnignore:

syntax:glob
LotsOChurn.solution
*.min.js

and they'll disappear from within Kiln.




How can I successfully convert my repository to Mercurial?

The Kiln Importer is a great tool, but it's also a bit simple: put in a repository on one end and get a repository in Kiln on the other end. Tweaking your repository so that it's ideally set up for Mercurial workflows is left as an exercise to the user.

While we're planning to make changes to the Kiln Importer to make it more advanced, here are some principles you can apply to manually convert your repository so that it works well in Mercurial.

Convert only what you need

Some version control systems, such as Subversion, will structure the repository as a file tree such that subdirectories are used to represent individual projects. In Kiln and Mercurial, you most likely do not want to convert the entire root trunk of the source repository.

A good test for determining which paths should be independent mercurial repositories is to ask, "which path would I use to checkout code if I needed to begin work on a single project and only this project?" That's usually the path you want to use when converting to Mercurial.

For example, let's say your repository tree in SVN looks like this:

/Trunk
    /CoolProject
         /WebApp
         /DesktopApp
    /Utilities
         /userscripts
         /powershell

In the above example, you would probably want to have Mercurial repositories for the following paths:

  • /Trunk/CoolProject/WebApp
  • /Trunk/CoolProject/DesktopApp
  • /Trunk/Utilities

Although CoolProject/WebApp and CoolProject/DesktopApp are related, they probably should be independent repositories unless you always work on development together. This also helps to separate the history of WebApp and DesktopApp, which are distinct products.

We could separate the Utilities/userscripts and Utilities/powershell repositories since they may not be related, it may simply be more convenient to work on all utilities at once. Further, I'm not concerned if the history of userscripts gets mixed with the history of Powershell.

Use the hgconvert extension

The Kiln import tool will do a good job converting your entire repo, but sometimes you want to be a bit more careful with what you bring over. For example, if you had binary debugging files that you would like to exclude from Mercurial's history, you may want to do the conversion manually.

Start with the documentation for the hgconvert extension. You'll need to enable the extension before using it. You can enable it by adding the following lines to your Mercurial.ini file:

[extensions]
hgext.convert=

You can use hg convert to convert from many different sources in very precise ways. You can even use hg convert against other Mercurial repositories.

Use hgconvert filemaps to exclude files

While you can use an .hgignore file to exclude certain files from your repository (see below), it's not going to help remove files from your repository's history. Do remove files and directories from the entire history of your repository, you need to use hg convert --filemap.

The documentation for --filemap is a bit sparse, so I'm going to include a few additional details here.

The filemap is a text file that you'll reference during the conversion. It allows you to specify multiple lines with exclude, include, or rename directives. Note that include will only include the files that are specified in include and will automatically exclude anything not included in an include statement. If you're using filemap to replicate .hgignore, you'll probably stick with exclude.

Let's say you create a filemap at C:\Temp\filemap.txt with the following contents:

exclude "Test.txt"     # exclude the file Test.txt from the 
                       # converted repo
exclude "libs/abc.dll" # use unix-style paths, regardless of OS
exclude "subdir"       # exclude all files from this subdirectory

In the example above, the first line will exclude Test.txt. Note that filenames are case sensitive. The second line will exclude abc.dll, which is in the subdirectory libs. Note the use of unix-style paths, which is required. The third line will exclude the entire subdirectory called subdir.

When I'm ready to run hgconvert, I can do so with a command like the following:

> hg convert --filemap C:\Temp\filemap.txt 
    http://path/of/source/repo .\DestinationPath

After running hg convert, you will have a new repository that excludes the files you specified from its entire history.

Use kbfiles and kbfconvert (largefiles as of Kiln 2.9)

NOTE: Kiln 2.9 ships with support for the LargeFiles extension, which is now part of Mercurial and not exclusive to Kiln. Most of the following still applies, but you should use LargeFiles instead of KBFiles. See How do I use the Mercurial LargeFiles Extension? for more details.

Kiln ships with an extension called kbfiles which can be useful for storing large binary assets in your repository. If you have large files in your repository for which having an atomic diff is unimportant, it's recommended (and sometimes required) that you use kbfiles.

For example, let's say you store documentation.pdf, a 35MB binary file, in your repository. Each time you commit a change to documentation.pdf, unless you have added the file as a bfile, Mercurial is going to diff the file to try to figure out exactly what changed. This is very resource intensive on Mercurial, and very often unnecessary. Instead, we use kbfiles, which will still store each revision of the file, but it won't try to diff it because a diff would be meaningless.

See How do you use kbfiles? for how to use kbfiles and additional explanation of why you want to use it. That documentation will give you a good idea of how to add kbfiles to an existing repository. I want to focus here on the conversion features of kbfiles with kbfconvert.

You can use kbfconvert to convert your repository to one with a new history so that specific files or files of a particular size are always added as kbfiles for the entire history of the repository. This is preferred if you're going to be pushing large binary assets to Kiln.

If you want to convert a repository to use kbfiles purely based on size, you can use a command like the following, which will automatically convert all files larger than 10 MB to use kbfiles:

> hg kbfconvert sourcerepo destrepo --size 10

What if you want to add files not based on size, but explicitly by file name? You can use kbfconvert to specify the names of individual files to add as kbfiles. The files you specify get added even if they are under the size specification. In the following example, TestSearch3.png, Test.txt.orig, and subdir\file2.txt are all going to become kbfiles in the converted repository, even though they are smaller than the specified file size of 1000MB.

> hg kbfconvert .\SourceRepo .\DestinationRepo TestSearch3.png 
    Test.txt.orig subdir\file2.txt --size 1000

Use a command like the above to explicitly convert specific files to using kbfiles in the converted repository.

Use an .hgignore file

Most Mercurial repositories benefit from an .hgignore file because it helps remove unnecessary cruft from the repository. For example, a Visual Studio solution is going to include .pdb debugging files and compiled binaries that don't need be included in the repository. In this case, an .hgignore is essential.

The documentation for hgignore is a good start. You might be able to search around for a sample .hgignore that matches the development environment for the project you're working on, but be careful that it's not too liberal in excluding files. For example, see this example .hgignore file for Visual Studio projects which we created. You can add the .hgignore file after the conversion, but it is not used by the hg convert process (unless of course you're converting a Mercurial repository that included an .hgignore file in its history).

Bringing it all together

We've gone over quite a few techniques above. Here's a set of practical steps you can apply to convert your repositories so that they're in good shape for use in Kiln.

  1. Identify which paths in your source version control system are going to be converted into individual mercurial repositories. You'll want to run the following steps for each repository.
  2. Create a filemap for the repository so that you exclude files that do not need to be in the converted repository.
  3. Run hg convert with the filemap you created so that you now have a Mercurial repository with only the files you need to actually work on code.
  4. Run kbfconvert against the converted repository from step 3 such that some files, specified either explicitly or by size, are included as kbfiles. The resulting repository will be much friendlier to Kiln and Mercurial.
  5. Add an .hgignore file to the converted repository from step 4 so that going forward, the repository only contains what it needs. Don't forget to hg add and hg commit the .hgignore file!
  6. Push the repository to Kiln.

Once you do the above steps, you should be good to go!




How do I import my files into Kiln from Visual Source Safe (VSS)?

For mainstream version control systems, such as Subversion, CVS, Git, Monotone, Perforce, and Bazaar, you can use the conversion tools that come with Mercurial to turn your historic source tree into a Mercurial-based one.

Doing so involves three steps:

  1. Enable the convert extensions in your Mercurial.ini (Windows) or ~/.hgrc (everything else), by adding the line

    convert=
    

    to your [extensions] group.

  2. Run hg convert <source> <target>, where <source> is the location of the old repository, and <target> is the name of the local Mercurial repository you want. For example, if my Subversion repository were at svn://source/svn, then I might run

    hg convert svn://source/svn source
    
  3. Create a new repository in your Kiln install to hold the converted source code. For the purposes of our example, we'll say that that repository is http://my.fogbugz.com/kiln/Repo/1/Repositories-Source

  4. Push to the newly created repository.

    cd source && hg push http://my.fogbugz.com/kiln/Repo/1/Repositories-Source
    

Update: Please try our "Import your existing Subversion/Git/Mercurial repository (or even a plain old directory of files on your local machine) into Kiln" tool by clicking the "Download and run the Kiln Import tool" link on any Empty Repository page.

We do not currently have plans to support more esoteric version control systems such as Visual SourceSafe or Vault. In the case of those systems, you can either create a new Mercurial repository and copy your source over, losing your history, or you can write your own tool to handle the conversion. We are aware that this solution is suboptimal, and hope to have a better solution available in the future.




How to import a subversion repos with active branches

hg convert actually makes this pretty easy. There is a config option called clonebranches that you just need to set to true, and it will make a separate repo for each branch:

hg convert http://url.to/my/svn/repo imported-branches --config convert.hg.clonebranches=1

What you will end up with looks like this:

imported-branches/
  .hg/             # ignore this .hg, you won't need it
  default/         # default branch, a.k.a. trunk/
    .hg/           # notice, no files in here yet. run 'hg update' to get files
  feature_a/       # all of your branches will be there own repos now
    .hg/
  feature_a/
    .hg/
  version-2.1/
    .hg/
  version-2.0/
    .hg/
  version-1.0/
    .hg/

In case it's not clear, you'll have a separate repo for each branch. They'll all be nested under another repo. Don't bother pushing this parent repo, it won't have anything in it.

Once you have the corresponding repos created on Kiln, just push each of the repos that you want to keep:

cd imported-branches
hg push -R default https://example.kilnhg.com/Repo/Project/Group/devel
hg push -R feature_a https://example.kilnhg.com/Repo/Project/Group/feature_a
hg push -R feature_b https://example.kilnhg.com/Repo/Project/Group/feature_b
hg push -R version-2.1 https://example.kilnhg.com/Repo/Project/Group/2-1
...etc...

For the branches you don't want, you can just delete them, though it wouldn't hurt to push them to Kiln, just for posterity's sake. You could keep them in a separate repository group.

Note that Mercurial and Kiln will both do the right thing, and recognize that these branches are all related. You'll be able to see differences between them on the Outgoing tab in Kiln, and should be able to pull and push between them locally with Mercurial.




Importing a subversion repository on a Mac

First I installed subversion, mercurial, and the subversion-python26bindings using macports.

sudo port install mercurial
sudo port install subversion
sudo port install subversion-python26bindings

Following the Mercurial instructions for repository importing, I created a .hgrc text file in my home directory and added these lines to enable the convert extension in mercurial:

[extensions]
hgext.convert=

Next I created an author map with the following lines to convert my unix user name to a new mercurial user name:

johnknox=John Knox <john@fooco.com>

I then imported my subversion repository trunk into a mecurial repository named myHg:

hg convert  --authors ~/hgUsername  file:///Users/johnknox/mySvn/myProject/trunk/ myHg

I moved into the new myHg repository and updated (oddly, no files were present except the .hg until the update)

cd myHg
hg update

I then checked that my history was properly imported

hg log Classes/mySourceFile.m

Finally, I pushed the repository into Kiln (see kiln for exact details):

  hg push "https://John Knox@fooco.kilnhg.com/Repo/Repositories/Group/myProject"



Import git repository into Mercury/KILN

The easiest way to move between Git and Mercurial is to use hg-git. The easiest way to install it, from the hg-git page:

The easy way

Run easy_install hg-git, then add make sure the following is in your ~/.hgrc:

[extensions]
hgext.bookmarks =
hggit = 

...and that's it!

Once it's installed, you can just run:

$ hg clone git://url/to/your/git/repo.git repo_hg

Once it's cloned, you just need to push it to Kiln:

$ cd repo_hg
$ hg push https://example.kilnhg.com/Repo/Project/Group/Repo

That's it!




How do I get a log of the Kiln Repository Import?

For Kiln 1.2+

After running the importer, the log will be at

%TEMP%\KilnImportLog <date> <time>.log
For Kiln 1.1

You can do that by using the windows Run command and typing in:

\path\to\KilnImporter.exe "kiln:import?log=true"

If it crashes, please submit the crash report. There will be no log file in this case.

If it fails to log in, you can click cancel. Then the log file will be at "%TEMP%\KilnImportLog " that you can send to us here at Fog Creek.

If it fails more seriously, without crashing, the location of the log file will be displayed in the importer, and can be copied if necessary.

Privacy note! For older version of Kiln, the log includes usernames and passwords. Please replace your password with something generic before sending us your log files.




Selectively converting SVN branches

It doesn't seem to be documented anywhere that I can find (even on the Convert extension page), but it seems to be the case that hg convert --branchmap will do what you want here.

Set up your branchmap.txt as follows:

Unwanted_Branch1 ### THERE IS A SPACE AFTER 'Unwanted_Branch1'
Unwanted_Branch2 ### THERE IS A SPACE AFTER 'Unwanted_Branch2'

Note: Make sure to put a space after the name of the branch, or it will complain about not getting a key/value pair. Also, make sure there is no newline at the end of the file, or it will also complain.

Then run your convert as you have been, adding --branchmap branchmap.txt.

You can also rename branches, if you want, using the branchmap:

Old_Branch1 New_Branch1
Old_Branch2 New_Branch2
Unwanted_Branch1 ### THERE IS A SPACE AFTER 'Unwanted_Branch1'
Unwanted_Branch2 ### THERE IS A SPACE AFTER 'Unwanted_Branch2'

Any branches you don't specify in the branchmap will be imported with their current name.




What’s the best way to adapt our existing Subversion project layout to Mercurial using Kiln’s Project > Repo Group > Repo heirarchy?

Your intuition is right all the way down.

In Subversion, storing lots of different projects in a single repository is commonplace. In Mercurial (and other DVCSes), storing one project per repository, and having lots of repositories, makes far more sense. That's why Kiln's repository interface is optimized to make it easy for you to organize your repositories in a meaningful way by project, group, and repo. So, at a base level, a normal Kiln install corresponding to your existing Subversion repositories would have at least two repositories, ProjectA and ProjectB.

There are several different ways to do branching in Mercurial, but the one we like best, and have put the most effort into supporting for Kiln 1.0, is to use one repository per branch. In this scenario, you would end up with four repositories in your example: ProjectA and ProjectABranch, and ProjectB and ProjectBBranch.

In answer to Kiln and FogBugz project correspondence: in general, we've found that making Kiln projects correspond to FogBugz projects is the right way to go, but we have exceptions in our own install in both directions (Kiln projects lacking a corresponding FogBugz project and FogBugz projects lacking Kiln ones). So it's likely you'd have two Kiln projects, each with two repositories, in your example. We've even made it so that you can link Kiln Projects to FogBugz projects, which sets the default project for code reviews on that repo.


Now, if you have an existing monolithic Subversion repository you converted, and you've decided that you want to break that into several smaller Mercurial repositories, I have good news and bad news. The bad news is that our importer tool cannot currently help you with that, so you're going to need to use the Mercurial command-line converter; and that the converted repositories will be "different" from the original, meaning that you'll need to re-create them in Kiln and re-clone them locally once the split is complete. The good news is you'll need to do that at most once, it's fast, it's pretty easy, and it'll make your life much better down the road.

To do it:

  1. Figure out how you want to split your repository. Hopefully, you have two or more directories, called (e.g.) foo/bar/ProjectA and foo/bar/ProjectB, that correspond to the projects you want to split out.
  2. Make a file called filemap-projecta.txt and put the following into it:

    include foo/bar/ProjectA
    rename foo/bar/ProjectA .
    

    Note that you should use Unix paths, even if you're doing this on a Windows system.

  3. On a clone of the repository that I'll assume is called OriginalRepo, run

    hg convert --filemap filemap-projecta.txt OriginalRepo ProjectA
    
  4. Go into the newly-created ProjectA repository, run hg up, and check the result. With luck, you should find that everything under foo/bar/ProjectA is there, and is now in the root of the repository.

  5. Repeat for other projects you want to split out, changing the lines in filemap-projecta.txt appropriately.
  6. Create repos in Kiln for each of the converted repositories.
  7. Push your new repositories into Kiln.

That's it. Please let me know if you have any other questions.




I have absolutely no clue how to get started with Mercurial. Can you please help me?

We're really happy to announce that we now have a really great introduction to Mercurial, called HgInit, available at http://hginit.com. It walks you through from knowing nothing about about Mercurial—or even nothing about source control—to knowing all the basics of Mercurial usage. If you're not sure how to get started, give the tutorial a try. It'll help you realize how easy Mercurial is to use, and you'll be all set up to start getting the most out of Kiln.




How do I use TortoiseHg? I have no idea.

There is actually a pretty decent quick start guide for TortoiseHg here:

http://tortoisehg.bitbucket.org/manual/0.9/explorer.html

...as well as Joel's generic Hg tutorial, hginit.com.

In general, there are two ways to interact with TortoiseHg. The first way is through its Explorer integration. When Tortoise is installed, it also installs a bunch of special hooks into Windows Explorer that allow it to display useful information about your repository. The details are described in the link above, but as an overview it shows:

  1. Overlays on the icons for files/folders inside a repository (shows you the state of those files and folders)
  2. New options in the Windows context menu (the one you get by right clicking on something in Explorer) to give you Mercurial controls. When you right-click inside a repository, you get access to the most commonly used commands.

In addition, you can interact with TortoiseHg through the command line. Most people familiar with Mercurial are used to typing commands like:

hg commit -m "Fixing mixed line endings that were causing diffs to look crazy"

Tortoise provides a GUI for nearly every Mercurial command. It can be accessed by replacing hg with hgtk. To get the GUI for the commit command in the previous example, you would type:

hgtk commit

The GUI gives you a place to enter a commit message, and a bunch of other useful controls (this is the GUI I use most frequently). The GUI that is least useful, for me, is the one the deals with push/pull/update. I simply find it easier to use the command line interface for these commands.

I would recommend trying them all out to find out which ones are most useful for you. For a day, simply replace your hg commands with hgtk. This should help you figure out which interfaces actually help you the most.




Doc on how to best configure/use TortoiseHG with Kiln?

Configuration should happen automatically when installing the Kiln Client from your Kiln installation. This'll automatically hook everything up and give you all of the Mercurial extensions that we recommend.

We're still working on documentation for best practices (with TortoiseHG, FogBugz, and everything else), so feel free to post any discoveries of your own here (help us out and we'll do the same!). There is also some documentation about our custom Mercurial extensions in your Kiln install -- just click on Resources | Kiln Client and Tools.




Mercurial Branches and Kiln’s Forks

There are a few issues you're encountering.

Mercurial has a specific command, called hg branch, that creates something called named branches. Mercurial tools historically did not interact with named branches in a user-friendly manner, and named branches have historically had very confusing and hard to understand behaviors: closing and abandoning branches was problematic, the meaning of the tip changeset and your tags became extremely complicated, and so on. At the same time, I'd be the first to agree that having some type of named branches is very useful.

What Kiln attempts to do is to obviate the need for named branches by making it very easy to have lots and lots of clearly named and well-organized related repositories on the server. We've opted to call those repositories "branch repositories," since their goal is to allow you to have a branch for experimenting on a feature/storing code for later review/etc. (Our terminology of calling them branch repositories, but having the action to make them be called "fork", is a usability bug that I think we need to fix.) All repositories in Kiln, whether branch repositories or central, are full-standing, independent, and (by default) only have the default branch. (You'll see it with a green background right next to tip when you're viewing a repository's history.)

What we encourage you to do is to keep separate branches of development in branch repositories in Kiln, forked off the main repository, rather than using Mercurial's named branches. In addition to the fact that tools support this workflow better, it becomes a lot easier to know what branch you're working with (just see where you cloned from), becomes trivial to discard changes (delete the branch repository), and makes it easy to try experiments without cluttering up the "real" repository's history.

So: we strongly encourage you not to use Mercurial named branches. We instead encourage you to use Kiln's branch repositories to make branch management easy, and to use a clone of a branch repository when you need to contribute to a branch.

If you really do want to use named branches, Kiln fully support them. You can filter to just a single branch head by selecting a branch from the "branches" drop-down menu when viewing a repository's history.




Kiln Branch and Merge How-To

One of the best things about DVCS in general is that branching actually works really well. Branching works well because merging works well. This kind of makes sense to anyone who has used Subversion or most other centralized version control systems. It's never the branching that's the problem; it's that gigantic scary merge back to trunk. Sort of like that adage, "it's not the fall that kills you, it is the sudden stop at the end." But I digress...

There are generally two reasons to create branch repositories in Kiln:

  1. You want to work on a feature, but you don't want to impact other developers working in your "trunk" repository.
  2. You want to create a long-running branch for yourself or another developer (workspace). The workspace allows you to work without disrupting anything that is going on in the "trunk" repository. This facilitates the "review everything before it goes into trunk" code-review process.

To branch in Kiln, you need to be logged into the Kiln web interface and browsing your repositories. Each repository has a small context menu marked by the blue arrow, and from that menu you can create a branch repository:

Create a branch

You just need to give the branch a name. Kiln will copy the contents and history of the repository to the new branch.

Branch created

It is important to reiterate here that the branch you just created is actually a full-fledged repository. You work with it just like you would any other repository. That starts with cloning. When I am working in a branch, I usually just move my copy of the "trunk" repository out of the way by renaming the folder on my machine (e.g., kiln -> kiln-trunk), and then clone the branch repository to the old trunk location. That way I don't have to change anything in my development environment.

> hg clone http://your.fogbugz.com/kiln/repo/my/kiln/branch kiln

Now you're ready to start working and making changes. As always, you should commit your changes locally and then push them to the server. This acts as a backup, plus it allows you to collaborate with your teammates by all cloning/pulling/pushing from the branch repository, if desired. While you are working in the branch repository, you can make whatever changes you need without fear of destabilizing the development work that is continuing in the "trunk".

Once you've finished your work in the branch repository, you need to get ready to merge back into "trunk". This is where the power of DVCS comes in, but it is also a bit different than what you are used to if you are coming from a typical, centralized VCS.

Because you have a complete repository on your machine that shares history with the repository you branched from, you can actually perform the merge on your machine, and record that action in source control. The fact that you have both the state of the files and the changes made during the merge in source control means it is nearly impossible to lose information during the merge. You can always roll back and re-merge if anything goes wrong.

To perform the merge, you'll first want to pull the changes from the "trunk" into your local repository and merge those changes with the changes you've made.

> hg pull https://your.fogbugz.com/kiln/repo/my/kiln/trunk
pulling from https://your.fogbugz.com/kiln/repo/my/kiln/trunk
searching for changes
adding changesets
adding manifests
adding file changes
added 4 changesets with 5 changes to 4 files (+1 heads)
(run 'hg heads' to see heads, 'hg merge' to merge)

> hg merge
4 files updated, 0 files merged, 0 files removed, 0 files unresolved

> hg commit -m "merge"

Once this is done, you will have saved, in your local repository, all of your changes plus all of the changes that have been going on in the "trunk" repository. You can now push your changes to the "trunk" repository and your branch repository without conflict.

> hg push https://your.fogbugz.com/kiln/repo/my/kiln/trunk
pushing to https://your.fogbugz.com/kiln/repo/my/kiln/trunk
searching for changes
kiln: successfully pushed 2 changesets
> hg push
pushing to https://your.fogbugz.com/kiln/repo/my/kiln/branch
searching for changes
kiln: successfully pushed 5 changesets

These pushes will ensure that all of the changes that were in the branch are now included in "trunk" repository on the server and vice versa. You now have the choice to either remove the branch repository, or keep it around if you plan on continuing development there. You must be an administrator to remove a repository, but you get to it through the Settings tab in the repository view:

Delete a repo




Where can I find the Kiln Client and Tools?

Open up a browser and login to your Kiln website. In the upper-right corner you'll see a menu titled "Resources." Click that and choose "Kiln Client and Tools."

Alternatively, you can go directly to: http://[your_kiln_url]/Tools/Downloads/KilnClient

Note: Use https for Kiln On Demand.




What is the Kiln Client?

Benjamin's answer here should suffice: http://kiln.stackexchange.com/questions/118/what-is-the-difference-between-tortoisehg-and-kilnclient, but the bottom line is that the Kiln Client is just TortoiseHg with a number of settings pre-configured and a couple Mercurial extensions that improve Kiln usability.




What is the difference between TortoiseHg and KilnClient?

The TortoiseHg that ships with KilnTools is no different from that you'd download directly from the TortoiseHg project. We do bundle a few extra extensions with it, and if you lack a Mercurial.ini file, we will set up one for you, but otherwise, there is (currently) no difference.

There is one extension you do likely want to enable, called kilnauth. This extension will use your Kiln cookies to log into Kiln, meaning that you only need to type your login and password once per Kiln installation that you access. To add it, add the line

kilnauth=

to your [extensions] section.




What do the Kiln extensions do?

We bundle a number of Mercurial extensions with the Kiln Client in order to improve your Mercurial experience. Here's a list of the extensions we bundle and what they do:

big-push

Helps pushing of large repositories by adding the --chunked flag to hg push. Using --chunked helps avoid timeouts and other network issues.

caseguard

Guards against case-insensitive file collisions in Windows.

fetch

hg fetch does a pull and update or pull, merge and commit, depending on which is necessary. It is closer to svn update and helps the transition from SVN to Hg.

gestalt

This extension attempts to help new Mercurial users by providing several commands to help learn how Mercurial works. The primary command provided is "hg next", which shows an overview of your local repository, its relationship and status to its parent, and what next actions you may wish to consider performing.

kbfiles

Improves support of large binary files in Mercurial by storing those files in a separate, centralized store on the server.

kilnauth

This extension knows how to capture Kiln authentication tokens when pushing over HTTP. This means you only need to enter your login and password once; after that, the FogBugz token will be stored in your home directory, allowing pushing without a password.

kiln

This extension allows you to directly open up the Kiln page for your repository, including the annotation, file view, outgoing, and other pages. Additionally, it will attempt to guess which remote Kiln repository you wish push to and pull from based on its related repositories.

nobranch

Gently suggests using Kiln's branch repositories instead of Mercurial's named branches.




I heard Kiln added kbfiles support in 2.0! What does that mean?

The Problem

Mercurial uses a lot of memory to store large files. If a repository is large enough it can't be pushed or cloned! The problem is that Mercurial stores files by computing the changes from one version to the next. This works great for code files because normally only a few lines of a file are changed. It doesn't work well for large binary files because commonly the changes from one version to the next will be dramatic.

The other problem is that cloning can take a long time. If someone added a two gigabyte file into your repository three years ago, and then removed it, you still have to download that file everytime you clone the repository.

The Solution

kbfiles! Based upon the work of Greg Ward, kbfiles stores large files outside of the Mercurial repository to avoid the out of memory problem. kbfiles support has been tightely integrated into Kiln and Mercurial. All of the commonly used Mercurial commands (and many others) work with bfiles.

To speed up cloning only kbfiles at the tip are downloaded. Older versions of the kbfiles are downloaded when they are needed. Also kbfiles keeps a cache of the bfiles you have downloaded so you won't have to download them again.

When To Use kbfiles

If your repository is larger than a couple hundred megabytes you should consider using kbfiles. If you decide to convert to kbfiles then files larger than about 5-10 megabytes should be stored as bfiles.

Using kbfiles

Read http://kiln.stackexchange.com/questions/1873/how-do-you-use-bfiles/1874#1874




How do you use kbfiles?

---Update! Use LargeFiles Instead!---

KBFiles has been replaced by it's successor, LargeFiles. Kiln currently (as of 2.9.x) still supports KBFiles, but the extension is no longer being developed and may stop working in a future version of Kiln. LargeFiles is a Mercurial extension, so it will be maintained and kept up to date by the Mercurial community.

---End of Update---

.

If you are still using kbfiles, you can read on, but please consider converting to LargeFiles as soon as possible.

How It Works

Before we get into using kbfiles we need to learn a little about how kbfiles works. For every bfile a standin file is stored in your repository. If you have a file bar/foo then the standin will be .kbf/bar/foo. The standin stores the SHA1 hash of the bfile. When you clone a repository first the Mecurial repository is cloned, then we look through all of the standins and download the file with the correct SHA1 hash from Kiln.

Using kbfiles

Commands like clone, commit, push, pull, and update all work with kbfiles without any new options. The following Mercurial commands work with kbfiles: add, archive, backout, bisect, clone, copy, fetch, forget, incoming, log, merge, outgoing, remove, rename, revert, status, summary, update, and verify. The Kiln web interface is exactly the same for kbfiles repositories as it is for normal repositories.

Working with a kbfiles repository is very similar to working with a normal repository. For example the following sequence of commands works on a kbfiles repository exactly like it would on a normal repository.

hg clone http://path-to-repo-on-kiln kbfilesrepo
cd kbfilesrepo
<edit a bfile>
hg commit -m 'Updated a bfile'
hg pull
hg merge
hg commit -m 'Merged'
hg outgoing
hg push

Creating a kbfiles Repository

We still need to create a repository that uses kbfiles. To use kbfiles with an existing repository you will need to convert the repository to a kbfiles enabled repository. The conversion is simple with the kbfconvert command, for example:

hg kbfconvert sourcerepo destrepo --size 10

This converts sourcerepo to destrepo. Any file larger than 10 megabytes will be stored as a bfile. Run hg kbfconvert --help for more information about the command. The conversion might take a few hours, but you only have to do it once.

Adding New kbfiles

Adding is a little different with kbfiles because you need to specify whether the new file should be stored as a bfile or a normal file. Add the --bf option to specify that a file should be added as a bfile, for example:

hg add --bf movie.avi

The command will add movie.avi as a bfile. Read hg add --help for other kbfiles options. You can also specify a size and a pattern in your hgrc file. Any file larger than that size in megabytes or that matches the pattern will be added as a bfile instead of a normal file. Below is an example kilnbfiles section of an hgrc file.

[kilnbfiles]
size = 5
patterns = glob:**.avi

Now any file added which is larger than 5mb or has the extension .avi would become a bfile. These options are only used on repositories which already have a bfile, normal repositories will not be affected.

Using Normal Repositories With kbfiles Enabled

The kbfiles extension should be left on even when you work with normal repositories. It will not change how normal repositories work, but in some cases it might change the output of a command slightly. For example hg outgoing will now print "Searching for changes" twice.

What Doesn't Work (Yet)

TortoiseHg integration with kbfiles did not make it in Kiln 2.0. You can't corrupt your kbfiles repository with TortoiseHg, but most of the commands will not work. Using TortoiseHg with kbfiles is not recommended even though some parts of it might work.

Some Mercurial commands don't work with kbfiles. For example hg serve won't work correctly. kbfiles repositories can only be pushed or pulled locally or through Kiln. Pushing or pulling through a repository on a networked drive will not work properly.




How do I use the Mercurial LargeFiles Extension?

Should I use LargeFiles at all?

Probably not. If you don't read anything else on this page, then read this: The benefit of LargeFiles is to save some bandwidth on push/pull/clone commands and save a few CPU cycles when making a commit. This comes at a cost though! LargeFiles is considered a "last resort" extension for Mercurial because it breaks the D in DVCS ("Distributed Version Control System").

There is a very specific problem that LargeFiles is designed to solve: in the case where a repository has binary files which change frequently, the changesets can get very large because binary files are not very easy to diff or to compress. LargeFiles basically solves this problem by allowing certain files to be treated in the same way that Source Control Systems like Subversion treated them: as snapshots of the file at certain times. Then when you do a pull, clone, or update command, you only get the snapshots of the LargeFiles that correspond with the relevant revision. This means you do not have a full copy of the repository on your local machine. You rely on the central repository (on Kiln) to store all the revisions of the LargeFiles and only pull them over the network when you update to a revision that needs them. This saves bandwidth and some CPU cycles.

I understand the cost/benefits trade-off, now how do I use LargeFiles?

Great! Are you sure? Go read the previous section one more time and be sure you really need LargeFiles. I'll wait... Okay, you seem pretty sure, so let's proceed.

To use LargeFiles you just need to enable the extension it and start adding files with the '--large' parameter like 'hg add --large largefile.pdf'. You might already have a bunch of binary files that you want to convert to be large files instead, which means you'll have to convert the repository.

NOTE: Once you convert your repository to use LargeFiles, it will no longer be related to the original repository. Because of this, you'll want to choose to do the conversion at a point in time when your entire team can switch to using the newly-converted LargeFiles repo.

Turning on the LargeFiles extension

Neither Kiln nor Mercurial will enable this extension by default when you install them. In order to turn the extension on you will need to add the following lines to the extensions section of your mercurial configuration file:

[extensions]
largefiles =

I highly recommend that you enable this on a per-repository basis, meaning enable it in the .hg/hgrc file in the repository rather than the user or global mercurial configuration file.

Do I have to convert my existing KBFiles-enabled repositories?

No, you don't have to convert your repositories. KBFiles is still supported by Kiln 2.9. However, LargeFiles is the successor to KBFiles so there will be no more updates or bug-fixes for KBFiles. Additionally, LargeFiles resolves an issue that existed in KBFiles which reduced the performance of many hg commands. So, it is not strictly required but it is highly recommended that you switch to LargeFiles to avoid the performance impact of KBFiles and to receive any code updates to the extension.

How do I perform the conversion from KBFiles to LargeFiles?

First, you'll need to be sure you have the latest version of the Kiln Client and Tools. You can download this from the Kiln page under "Rescources". Once you have this installed, the conversion is a simple two-step process. Each of these extensions have methods to convert from a normal repository to one using the extension and vice versa, so it is through these commands that we will perform the conversion.

You need to first convert from a KBFiles-enabled repository to a normal one, and then convert that normal repository to a LargeFiles-enabled one. The following two commands will perform these conversions (the '--size 10' parameter in the second command indicates that any file over 10MB should be converted to a LargeFile. See the LargeFiles page for more complex patterns):

hg kbfconvert --tonormal /your/kbf/repo/location /temporary/normal/repo
hg lfconvert --size 10 /temporary/normal/repo /new/largefiles/repo

Now you have a new LargeFiles repository with all the same data as was in your original repository! You can push this new repository into Kiln and get everyone to start using it. The temporary repository created by the first command can safely be deleted from your harddisk, and it would probably be wise to delete the original KBFiles-enabled repository from Kiln to ensure that everyone switches to using the new LargeFiles repository (don't worry, kiln doesn't delete the data from the repository, it just marks it as deleted. You can recover it later if anything goes wrong).

How do I enable LargeFiles on a normal repository?

First, you'll need to be sure you have the latest version of the Kiln Client and Tools. You can download this from the Kiln page under "Rescources". Then you just need to convert the repository with the following command (the '--size 10' parameter indicates that any file over 10MB should be converted to a LargeFile. See the LargeFiles page for more complex patterns):

hg lfconvert --size 10 /your/normal/repo /new/largefiles/repo

Now push this new repository into Kiln and start using it! You can delete the original KBFiles-enabled repository from Kiln to ensure that everyone switches to using the new LargeFiles repository (don't worry, kiln doesn't delete the data from the repository, it just marks it as deleted and makes it inaccessible. You can recover it later if anything goes wrong).




How do I clear kilnauth cookies?

You can run hg logout on the command line to clear your cookies once, and you'll have to login when you run your next push/pull/inc/out command.

If you'd like to permanently disable kilnauth, you can simply edit your Mercurial.ini file and remove the line that starts with "kilnauth=".

Mercurial.ini should be found in your home directory (C:\Documents and Settings\{username} on XP...)




How do I use kilnauth from Cygwin?

Make sure you're using kilnauth. Then use cmd (which will allow interactive login) to authenticate with Kiln once. Finally, copy the _hgcookies from your Windows home directory to your Cygwin home directory.

cp /cygdrive/c/Documents\ and\ Settings/[YOUR USER NAME]/_hgcookies ~




How can I install Kiln’s Mercurial extensions manually?

Sure. It's actually quite simple:

  1. Grab the extensions themselves by clicking on Resources -> Kiln Client and Tools
  2. Download the extensions zip bundle and extract it to your favourite location.
  3. Open the file .hgrc in your home directory. If it doesn't exist, create it.
  4. Add a section called [extensions] if one does not already exist
  5. Add one line for each extension you wish to include that names the extension and points to where on disk you've stored it

For example, if I wanted to use all 7 extensions, and I had saved them to ~/KilnExtensions, then my .hgrc might look like this:

[ui]
username=Your Loginname <you@example.com>

[extensions]
gestalt=~/KilnExtensions/gestalt.py
kilnauth=~/KilnExtensions/kilnauth.py
kilnpath=~/KilnExtensions/kilnpath.py
big-push=~/KilnExtensions/big-push.py
kiln=~/KilnExtensions/kiln.py
caseguard=~/KilnExtensions/caseguard.py
kbfiles=~/KilnExtensions/bfiles/kbfiles

[auth]
kiln.prefix=yoursite.fogbugz.com
kiln.username=Your Loginname

[kiln_scheme]
kiln=http://yoursite.fogbugz.com/Kiln/Repo

Of course, there are a plethora of other extensions for Mercurial, both built-in and third-party. You might have others under the "[extensions]" section.

If everything worked correctly, you should be able to pull up the help documentation by typing hg help extensionname. For example:

gozer:~ benjamin$ hg help kilnauth
kilnauth extension - stores authentication cookies for HTTP repositories

This extension knows how to capture Kiln authentication tokens when pushing
over HTTP.  This means you only need to enter your login and password once;
after that, the FogBugz token will be stored in your home directory, allowing
pushing without a password.

If you ever need to logout of Kiln, simply run "hg logout''

list of commands:

 logout   log out of http repositories

use "hg -v help kilnauth" to show aliases and global options
gozer:~ benjamin$ 

That's it.

If your kiln site is using SSL (i.e. the clone URL starts with https://), you may get an error like this:

Warning: mydomain.kilnhg.com certificate not verified (check web.cacerts config setting)

If you do, see this post for the fix.




What do you do to make sure my source code is safe?

We know that hosting source code is different than hosting your FogBugz database. We host our own source code with Kiln, and we have been using Kiln internally for months.

All of your source code is stored on an isolated network that can only be accessed by the Kiln web servers. Every bit of Kiln is hosted on the same secure infrastructure as FogBugz On Demand. We will never examine the contents of your repositories unless we are diagnosing a technical problem and have already received your express permission.

All repositories are mirrored on redundant hardware in real-time. Each day we take a backup of everything, and each night we grab those backups and store them off-site. Offsite backups are maintained for 30 days. We will always take protecting your code as seriously as we do our own.




How do I start a code review?

Here's a video that we created which explains how to create code reviews in Kiln:

/fogbugz/Videos.html?tab=kiln&video=Pu1NmykTxWM




What is the best workflow for performing a series of code reviews?

It actually is accessible directly from Kiln—and when accessed that way, has the behavior you want. In Kiln, under the "Reviews" drop-down that's on the right side of the toolbar, you should see a list of all reviews that are opened by you or assigned to you. You do not need to make a FogBugz filter for this. This will also go directly to the review, rather than go to the FogBugz case backing the review.

The Reviews menu is globally available in Kiln, so you can use it to go directly from code review to code review. That's how I normally edit my code reviews en bulk. Like FogBugz, unread code reviews will be blue, and read ones will be purple—enforced on the server side, so that you can trust its read/unread status even as you move between machines or browsers.

We've noticed that users are not realizing that Kiln has this functionality, and will try to make the menu more obvious in upcoming versions of Kiln.




How do I add a commit to an existing code review?

NOTE: This only applies to Kiln versions lower than 2.9

Because a code review is a case, all you need to do is associate the new changeset with the review case, and then add it to the review.

There are two ways to associate a changeset with a case:

  1. If you haven't already committed that changeset, simply add "Addresses review 1234" or "Bugzid:1234" to the commit message and then push it to the server. It will be automatically linked to Case 1234.
  2. If you have already made the changeset, then:
    1. Open it in Kiln
    2. Click "Add Case Link"
    3. Specify the case number for the review you wish to add, and click "Add"

Once you've associated the changeset with the review case, an "N more changeset(s) are linked to this review" message will appear at the top of the changes pane in the review UI.

  1. Click "Add to this review..."
  2. A changeset selection window will pop up. Make sure the changesets you want to add are selected, and click "Ok"

You're done. Kiln will update the review case to indicate that a changeset was added. This automatically notifies the person the review is assigned to (assuming that's not you, because why would we email you to tell you what you just did?).

We know that this workflow isn't perfect, and we'll be working to streamline it in upcoming versions of Kiln, but it will get the job done.




What’s with the new review system?

Kiln's old review system worked well for us, but we know that it didn't work well for a lot of our users. Kiln reviews, like FogBugz cases, could be assigned to only one person at a time, but you guys told us that having multiuser reviews was really important to you. So we went back to the drawing board, and for Kiln 2.4, came out with an entirely new way to do reviews.

An intermittent state of a Kiln multiuser review

So how do they work? You start the same as always: from a changeset, the history view, the incoming or outgoing pane, or anywhere else that changesets are sold, click the "New Review" button, and choose your reviewers. Your review will then be opened...but now, a single review for all reviewers, not one review per reviewer.

All participants will be notified that they have a review available. It will be listed in the My Reviews, and is accessible in FogBugz via the My Kiln Reviews filter and the reviewedby:me search axis. Reviewers are also automatically subscribed to all reviews they participate in, so if you have Kiln set to send you email, you'll get emails whenever anyone comments.

The review now proceeds as before, with one critical difference: every participant individually decides whether to approve the review. At any point, the status of each reviewer appears at the top of the case (see the above screenshot).

A code review that has reached consensus

There are three things that can happen to a review:

  1. Everyone can approve or reject the review. If this happens, the review is automatically Approved or Rejected, depending on how reviewers voted. You can then accept the verdict and close the review.
  2. There can be deadlock, with some reviewers approving, some rejecting. In this case, the review may be Abandoned, meaning that no consensus could be reached.
  3. If only some people bother weighing in, but they all agree, you can accept the current consensus of the review and close it if you don't need to wait for everyone to approve. If removing those who haven't weighed in (or, for that matter, who disagree) results in consensus, the review will automatically switch to Approved or Rejected. Conversely, adding new reviewers to an already-completed review will automatically reopen the review as lacking consensus.

The new system ships out today to licensed customers, and has been available on Kiln On Demand since late last week.




Kiln and Visual Studio 2008

Integrating Kiln with Visual Studio is just a matter of choosing one of the integration tools for Mercurial. Some of the recommend ones to check out are:




How do I use the Electric DAG?

Kiln 2.0 brings a new feature for understanding and exploring your code's history. We call it the Electric DAG.

Mercurial is called a "DAG-based DVCS" because the relationship of each changeset with its parents (the changeset that it is based on) forms a directed acyclic graph. A mathematical understanding of this isn't necessary to use Kiln, of course, but the DAG nature of your repository's history exposes some interesting facts.

You can find the DAG view of your repository by clicking "History" at the top of any repository. You'll see your complete repository history, with the tip at the top. Each changeset is connected to its parent (or parents, for merges) by a colored line. By following these lines, you can trace a changeset's ancestry down the page, all the way back to the beginning of your repository. You can also trace a changeset's line up the DAG, to find what other changesets include those changes.

Of course, tracing lines on a screen isn't the easiest way to track your code's history. This is where the Electric DAG comes in. Click the background of any changeset in that list, and---zap!---the ancestors and descendants of that changeset are highlighted. Changesets that aren't related, that is, which aren't an ancestor of the selected changeset and don't descend from the selected changeset, are shown in gray. Only the bright changesets are related to the selected one.

The Electric DAG can reveal what changes are included in a tagged changeset, such as a specific build version. Select the tagged changeset, and look at the highlighted changes below it:

All the highlighted changesets were included in Version 1.7. Any gray changesets aren't ancestors of the changeset tagged Version-1.7. For example, Patrick's change with the message "sort diffbookmarks() output" is included in the new version, but David's fix to "remove unused variable" isn't.

The electric DAG can also tell you what tagged changeset a given changeset is included in. For instance, let's select David's "remove unused variable" changeset, which we saw didn't make it into Version 1.7:

Now looking at the descendants of that changeset (which are above it on the DAG), we see that the first tagged changesets that's highlighted is Version-1.7.1. So David's fix will be included in that release---go ahead and tell that frantic customer that his fix is on the way (I'll wait here). As you expect, the Version-1.7 changeset is gray, because David's changeset wasn't included in that release.

The electric DAG has one more trick up its glowing blue sleeve. First, click any changeset to electrify it. Then, hold the Control (ctrl) key on your keyboard and click another changeset. Here, I've clicked the changesets tagged Version-1.7.1 and Version-1.7:

What's going on here? Kiln has highlighted all the changesets that are different between the ancestries of the two tags. In other words, every highlighted changeset is included in version 1.7.1 but not in version 1.7. The changeset we were just looking at, "remove unused variable", is highlighted, because it made the 1.7.1 release but not the 1.7 release. All the other highlighted changesets are in the same situation: ready to go for the next release.

Think how easy it would be to write release notes for 1.7.1, or for QA to know just which bugs have been fixed between releases. Wonder no more about when a vital fix was merged into the main repository, or when a customer will be able to use a new feature. Kiln's Electric DAG leverages the power of Mercurial to delve deep into your repository's history, so you can know your code.




Kiln 2.0 Search

Indeed, there is a new search feature that's available in Kiln 2.0, and it's designed so that you can quickly find what you're looking for in Kiln and navigate around your code with ease.

There are three basic types of search results available in Kiln 2.0: Changesets, Filenames, and Code results.

Changesets

Kiln 2.0 gives you the ability to search through commit messages in a repository to find the exact changeset you're looking for. For instance, if you're looking for that changeset where you made changes to the vnode struct, you could search for vnode and you'd end up seeing something like this:

alt text

But changeset search goes even further. If we want to narrow these results by changeset author, say myself, I can filter by username by adding author:Andrew into my search query.

alt text

Ta-da! I've restricted my results from the first search in order to find only the changes that I've made.

But over time, there could be hundreds of changesets authored by me, and many of them could contain similar words. Thankfully, we can tell Kiln to only look for changesets within a certain date range. For instance, if I want to find all the builds our awesome build manager has tagged in the last two weeks, all I need to do is search "added tag" author:rock date:-2w..today and the changes I'm looking for are right in front of me.

alt text

To find all changesets that are contained between two tags, search for the two tags separated by two colons, e.g. "Version_1-0::Version_2-0" to find everything new in version 2 of your application.

Filenames

Often, you'll want to go into Kiln and look at a file's history or you'll want to view the contents of a file you don't have cloned to your computer. File search is meant to get you to the file you're looking for without having to navigate the repository file tree. If I want to double-check how a specific function works in our kiln Mercurial extension, searching for kiln.py brings up the file I'm looking for. From here, I can annotate the file, view the history, or just look at the file contents. It's that simple!

alt text

Code

One of the most powerful features of Kiln Search is the ability to search for items inside your code. If you're looking for the definition of a specific function or variable, searching using the query foo or defs:foo will return the lines inside your files where foo is defined.

alt text

Likewise, a search for refs:foo will return the line of code where foo is referenced.

alt text


How does Kiln determine which repository to search in initially?

Kiln tries to guess which repository is most likely to have the result you're looking for based on a few factors. First, if you're already on a repository screen or have used the repository selector widgit on the search page, then Kiln will look in that repository first first. If not, Kiln looks at your most commonly used repositories and find the first repository with a result.

Failing both of these, Kiln will show you the repository with the most results.

I keep forgetting all these search axis. Is there any other way for me to use them?

Remembering the name of each search axis can be difficult, especially if you don't use Kiln search often. Although using the name of the axis in the query will be the fastest way to use an axis, the Search Options popup on the results page gives you a friendly interface to the same features.




Kiln 2.0: Command Line Path Guessing

You must have met an awfully smart birdie, then! Path guessing tries to remove the constant pain of either adding a bunch of paths to your hgrc file or copying URLs back and forth all day long. The incoming, outgoing, pull, and push Mercurial commands are supported for this extension.

After you install the Kiln Client, which includes the kiln extension, you should see the following section added to your Mercurial.ini file:

[kiln_scheme]
kiln=http://<yourdomain>.kilnhg.com/Repo

Path guessing uses these entries to determine the location your Kiln account. If you use multiple Kiln installs, path guessing will support guessing to different installs so long as they are all specified here.

After cloning a repository, I see that the only path available to me (the default path) is the repository I cloned off of, in this case my personal andrew branch of a project.

PS C:\demo> hg paths
default = https://songexe.kilnhg.com/Repo/Website/2-0/andrew

Now lets say I've made some changes and want to push them out to my branch. Luckily, that's my default branch, so I can just type hg out:

PS C:\demo> hg out
comparing with https://songexe.kilnhg.com/Repo/Website/2-0/andrew
searching for changes
changeset:   29:6951f1d98d7b
tag:         tip
user:        Andrew Song <andrew@fogcreek.com>
date:        Thu Aug 19 14:00:59 2010 -0400
summary:     Added newfile.txt to the repository

If I just type hg push now, it'll get pushed out to my default branch:

PS C:\demo> hg push
pushing to https://songexe.kilnhg.com/Repo/Website/2-0/andrew
searching for changes
remote: kiln: successfully pushed one changeset

Now I'd like to push this change to the parent repository. Previously, I'd have to go into Kiln and manually grab the URL for my parent. Thankfully, we now have path guessing! By using the command hg kiln --targets or hg kiln -t for short, we can see a list of all non-empty repositories related to this in Kiln:

PS C:\demo> hg kiln -t
The following Kiln targets are available for this repository:

    http://songexe.kilnhg.com/Repo/Website/1-0/OldWebsite
    http://songexe.kilnhg.com/Repo/Website/2-0/Parent
    http://songexe.kilnhg.com/Repo/Website/2-0/andrew
    http://songexe.kilnhg.com/Repo/Website/2-0/david
    http://songexe.kilnhg.com/Repo/Website/2-0/kareem

Now, all I need to do is completely and uniquely specify any URL part.

PS C:\demo> hg push Parent
pushing to https://songexe.kilnhg.com/Repo/Website/2-0/Parent
searching for changes
remote: kiln: successfully pushed one changeset

Since Parent was a unique part of the URL slug, path guessing knew exactly which repository I meant and pushed to it without forcing me to fumble around with URLs.

What if I had typed hg push 2-0 instead? Since this doesn't uniquely match any part of the URL, path guessing will just display a list of all matching targets:

PS C:\demo> hg push 2-0
abort: 2-0 matches more than one Kiln repository:

    http://songexe.kilnhg.com/Repo/Website/2-0/Parent
    http://songexe.kilnhg.com/Repo/Website/2-0/andrew
    http://songexe.kilnhg.com/Repo/Website/2-0/david
    http://songexe.kilnhg.com/Repo/Website/2-0/kareem

Hopefully, path guessing will improve your interaction with Kiln by removing some inconveniences and streamlining your workflow. It sure has made my life easier!




What’s new in Kiln 2.4.105?

If you're coming from the last On Demand release, then you've got two major new features:

  1. New Review System: We've documented this elsewhere, but the review system has been entirely overhauled to focus around multiple simultaneous reviewers.
  2. Kiln Customizations: You can now add JavaScript-based customizations to Kiln via a tool we call Glaze. We'll have full documentation on this feature available later today.

But if you're coming from a licensed release, you get a lot more:

  1. A totally new review UI that should be a lot easier to work with, including threaded replies, a new control scheme, better attachments, and more. (This is in addition to the changed workflow documented above. Really, if you're coming from Kiln 2.3, you're going to be getting a massively revamped, tremendously improved review system that we think you'll really like.)
  2. Prefabricated web hooks, so you no longer have to run a little service just for common integration points like HipChat or your continuous integration system.
  3. Support in the web UI for Mercurial bookmarks, so you can get nice lightweight-style branching.
  4. A brand-new way to see related repositories, making it easier than ever to keep track of everything going on in your project.
  5. Revamped integration with FogBugz, changesets shown in-line in tthe cases that they're associated with.
  6. Vastly revamped public repositories, making it easier than ever to share your open-source projects with the outside world.
  7. Customizable diff options so you can ignore whitespace, change tab sizes, view diffs side-by-side, and more.
  8. A new search tool, the :: operator, which allows you to automatically search for a range of changesets. For example, you can do Kiln_Release_2.3.0::Kiln_Release_2.4.0 to see all changes between Kiln 2.3.0 and 2.4.0 (assuming you have access to Kiln's source code, that is).
  9. Updated versions of the Kiln client tools, allowing you to experience the newest versions of TortoiseHg and Mercurial.
  10. The ability to tell Kiln never to show certain files in diffs, making it easier to focus on the importants parts of a changeset.
  11. DAG-based file histories, so you can get a better idea what the actual history of your file was.
  12. Support for custom logos, so you can have your own corporate brand instead of our beloved Dodo bird if you so choose.
  13. Lots more Ajaxy HTML5 goodness, dramatically speeding up repository browsing.

And those are just the major features. There's a lot of other subtle improvements, such as the ability to jump to the DAG directly from a changeset, or the ability to open reviews from the incoming pane, or the fact that repo descriptions are now displayed in the UI to help guide your team where they should be working.

We really believe you'll love this release. It represents months of work by the Kiln team, and we're happy to finally get it into your hands.




How do I view the Annotation of a file in Kiln?

Yes, Kiln has this feature built-in.

  1. In your repository, under the Files tab, find the file you wish to annotate and click on the file name.
  2. From here, there is an Annotate button on the top-right of the screen. Clicking this will annotate the file you're currently browsing.

You can also use the TortoiseHg application to do this from your local machine. While currently browsing your working directory in a command prompt, type hgtk annotate <file path goes here> and it will do a much more detailed annotation.

I hope this helps -- please let us know if there's something more you'd like to see in Kiln!




How can I find out which version of Kiln I’m running?

The version information for Kiln is located in the footer at the bottom of every page.




Do I own both {my}.fogbugz.com and {my}.kilnhg.com?

That's correct!

If you have an On Demand account, your Kiln installation is available at {your}.kilnhg.com, and FogBugz is available at {your}.fogbugz.com.

They're tightly integrated and logins are hooked up to eachother, so logging into one will log you into the other, and vica-versa.




How can I easily let guests see my code?

Yep! Any of your projects in Kiln can be made "Public", so anyone can clone or pull from the repositories in that project, even if they don't have a Kiln account. You can enable public access on none, any, or all of your projects. Here's how:

  1. Find the project you want to make public, then choose "Configure". On the project configuration, choose "Enable Public Access". Project Configuration page

  2. Choose "Public Access", then click OK. Public Access page

  3. That's it! Public projects are marked with an unlocked lock icon. Lock icon

Public access is read only; only authorized users on your Kiln account, with the appropriate permissions, can push to or configure a public repository. Of course, your private projects will still be accessible only to authorized users, and you can disable public access by choosing "Private Access" in step 2, above. We hope this feature makes it easier for you to share your open source and other public code with your users, while keeping all your code together in Kiln.




Should I use more than one repository?

The short answer:

Yes, with a DVCS, you should use at least one separate repo per project, including shared projects and libraries.

The long answer:

We had basically the same setup here at Fog Creek when we were using Subversion. One big repo for everything. When we switched over to Mercurial, we quickly learned that DVCSs don't work the same way, and aren't really suited for one large repository like that. Now we have several repositories for each project.

For example, with Copilot, we have several different moving parts that are relatively independent of each other:

  • Helpers (downloadable EXE clients)
  • Reflector (server that links communication between helpers)
  • Website
  • Billing System
  • Aardvark (shared library used by the reflector, website, and billing system)

For each of those parts, we've created a separate repository group and we keep a devel and stable repository in each of those groups. New features go into devel and eventually get merged forward to stable, while bug fixes go into stable and get merged back into devel.

To keep everything in sync for deploy, we use tags. In Subversion, tags are a pain because they're really not a tag as much as they are a full copy of your code in a different directory. With Mercurial, a tag is more like meta data on the repository, and you just treat them like a version number.

So let's say I need to deploy a new version of the Copilot website. To do it, I'll need a copy of website-stable and a copy of aardvark-stable. First, I tag each of those repos on my local machine (we have a batch file that does it for us, calculating out the tag number, e.g. Website000123). Then we kick off the build process with our tag, which clones both repos from the server into a build directory and runs hg up -C Website000123 to update them to the tag. Then it builds and deploys.

If I ever need to go back in time to that particular build, I can just run the same command, hg up -C Website000123 in each repo. You should notice that we tag both the Website and the Aardvark repos with Website000123, instead of tagging Aardvark with Aardvark000123. This is because we'll also be tagging Aardvark for our reflector builds (Reflector000456) when they go out, and we want to be able to know which was which.

We're currently working on some in-depth tutorials on exactly these sorts of topics. In the meantime, the following SE pages are a good start on some of the repo management topics I've mentioned here:

Update: The long-promised tutorial is out! Check it out HgInit.com




Can I control Kiln’s display of diffs and files?

We sure do! As of Kiln 2.4, every diff and file view lets you customize the display to your liking. When viewing a file, click the gear in the top-right corner; on a diff or in a code review, click the gear in any diff's header:

All displayed files and diffs have two configuration options: visible whitespace and tab size. Enable "Show whitespace" to add subtle markers for tabs and spaces in your code.

Spaces are marked with a dot, while tabs are a small arrow, so you can easily spot inconsistent whitespace. If you don't like the default 8-space tabs, change "spaces per tab" to your preferred size. See the result in this Makefile:

In addition to these options, diffs have two additional customizations. Choose to ignore whitespace changes to only show the changes made to visible characters. Let's take as an example changeset 0c84afa1d622 from Mercurial itself. The standard diff for this change looks complicated:

However, ignoring whitespace changes simplifies things, and reveals what the diff actually changed:

If you're often reformatting code, this display can be a lifesaver. This option is equivalent to the -w/--ignore-all-space flag at the Mercurial command line.

The second option for diff display changes from a standard, stacked diff to a side-by-side diff. You might be familar with this style from kdiff3 or other visual diff tools. Rather than showing removed and added lines interleaved in a single column, side-by-side diffs show removed lines on the left and added lines on the right:

becomes

Compare each line's changes directly across the screen. These new options allow you to customize Kiln's display of your code to your liking. I love to tweak my workspace, and these options make it easy to get Kiln working just right for me.