Accessing code repositories

Context

The Orthanc server and most of its plugins are versioned using Mercurial on a self-hosted server.

The Orthanc project started back in 2011, back in a time where Mercurial and Git were equally popular. Sébastien Jodogne, the original author of Orthanc, decided to use Mercurial given the higher simplicity of its set of commands, and given the fact it is safer to use for less experienced users.

As pointed out on Wikipedia, the “Git vs. Mercurial [debate] has become one of the holy wars of hacker culture.” We certainly don’t want to endure this debate in the context of the Orthanc ecosystem. The fact is that a distributed revision-control was needed for Orthanc, and that both Git and Mercurial have a similar set of features.

If Orthanc were started in 2020, maybe we would have used Git, or maybe not. But the Orthanc ecosystem is not at all about versioning systems. We want to be entirely dedicated to lowering barriers to entry in the field of medical imaging. As a consequence, the choice of Mercurial should be considered as a part of the history, and we simply ask people to accept it as a fact.

Regarding the reason behind self-hosting, Orthanc was hosted on Google Code between 2012 and 2015, until it was shutdown. In July 2015, Orthanc was moved to Bitbucket by Atlassian. Unfortunately, in July 2019, Bitbucket announced that Mercurial support would be dropped on June 2020, forcing us to deal with another migration.

We are of course grateful to Google and Atlassian for having hosted Orthanc during 8 years. However, we cannot afford the cost of periodically coping with hosting migrations. We prefer to have a simpler environment, yet under our full control. As a consequence, starting Q2 2020, Orthanc is hosted using the official hg serve tool.

Accessing Mercurial

Read-only access

Anybody has full read-only access to all of the Orthanc official repositories, on our self-hosted server. As the hg serve tool that is used by our Web server tends to be slow, we recommend people to locally clone our Mercurial repositories.

Locally cloning one of those Mercurial repositories (say, the main orthanc repository) is as simple as typing:

$ hg clone https://hg.orthanc-server.com/orthanc/

You can then use separate tools such as TortoiseHg to browse the code with richer features than the Web interface.

You might have to set up a host fingerprint in the Mercurial configuration. Add the following lines to your ~/.hgrc file:

[hostfingerprints]
hg.orthanc-server.com = 97:EB:6E:97:18:BD:B7:73:E3:33:E0:DE:23:74:40:C5:A1:EA:3F:BE

For reference, here is the command that was used to generate this SHA1 fingerprint (click here for more information):

$ openssl s_client -servername hg.orthanc-server.com -connect hg.orthanc-server.com:443 \
  < /dev/null 2>/dev/null | openssl x509 -fingerprint -sha1 -noout -in /dev/stdin

Important: As our certificates are changed periodically, you’ll have to regularly update your configuration file once Mercurial complains about an unexpected fingerprint.

Recent versions of Mercurial

While cloning the repository, you might face an error similar to:

abort: error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:661)

In such a case, you must explicitly add the cryptographic fingerprint of our code server using a more recent option than the hostfingerprints option. To this end, edit the configuration file of Mercurial (by default on Microsoft Windows, %USERPROFILE%\Mercurial.ini), and add the following lines:

[hostsecurity]
hg.orthanc-server.com:fingerprints=sha256:DC:91:21:26:AD:12:83:44:95:A5:16:EC:CB:CA:CF:3D:41:92:04:36:19:39:A0:02:B5:CD:58:94:E2:2C:56:F9

For reference, here is the command that was used to generate this SHA256 fingerprint (click here for more information):

$ openssl s_client -servername hg.orthanc-server.com -connect hg.orthanc-server.com:443 \
  < /dev/null 2>/dev/null | openssl x509 -fingerprint -sha256 -noout -in /dev/stdin

Write access

Only the core developers of Orthanc have direct write access to the Orthanc repositories (through SSH). Core developers can clone a repository with write access as follows:

$ hg clone ssh://hg@hg.orthanc-server.com/public/orthanc/

Submitting code

We will of course be extremely grateful for receiving external code contributions to the Orthanc repositories!

However, one of the weaknesses of our self-hosted infrastructure is that is does not support automation for pull requests. This section explains the two accepted ways for communicating contributions: by submitting a patch, or by exchanging a bundle.

Importantly, before any contribution can be accepted into the Orthanc repositories, its author must sign a CLA. This allows both the University Hospital of Liège and the Osimis company to act as the official guardians of the whole Orthanc ecosystem.

Also, make sure to read our FAQ if submitting code.

Simple patch (import/export)

If you want to propose a simple contribution, the most direct way of passing it on the Orthanc community is by creating a simple patch.

First make sure to pull the latest version of the code repository, then work on your modification in the default branch (i.e. in the mainline code):

$ hg pull
$ hg up -c default
[...make your modifications...]

Once your contribution is done, here is how to export a patch:

$ hg export -r default > /tmp/contribution.patch

Once the patch is ready, you can send the /tmp/contribution.patch file to the Orthanc community, e.g. by submitting it onto our official discussion group. The core developers would reintegrate such a patch by typing the following command on their side:

$ hg pull
$ hg up -c default
$ hg import /tmp/contribution.patch

Exchanging a bundle

If your contribution is made of several changesets (commits), you should work in a dedicated branch, then submit a Mercurial bundle for this branch.

First make sure to pull the latest version of the code repository, then create a branch, say my-user/my-fix, that derives from the default branch (which corresponds to the mainline code):

$ hg pull
$ hg up -c default
$ hg branch my-user/my-fix

WARNING: Please chose an unique, explicit name for your branch, and make sure that your username is included within for traceability! The name my-user/my-fix is only here for the purpose of the example.

You can then do all the modifications as required (including hg add, hg rm, and hg commit) in the branch my-user/my-fix. When you’re done, create a Mercurial bundle that gathers all your changes against the source repository as follows:

$ hg commit -m 'submitting my fix'
$ hg bundle /tmp/contribution.bundle https://hg.orthanc-server.com/orthanc

Obviously, make sure to replace https://hg.orthanc-server.com/orthanc by the location of the source repository.

Finally, you can submit the file /tmp/contribution.bundle to the community, just like for simple patches. Note that this procedure inherently corresponds to the manual creation of a pull request.

The core developers would reintegrate such a bundle into the mainline by typing the following commands on their side:

$ cd /tmp
$ hg clone https://hg.orthanc-server.com/orthanc/
$ cd /tmp/orthanc
$ hg unbundle /tmp/contribution.bundle
$ hg up -c default
$ hg merge my-user/my-fix

Issue tracker

The official bug tracker of the Orthanc project runs thanks to Bugzilla.

We have done our best to automatically import most of the history from the old BitBucket bug tracker.

Before posting any issue, make sure to carefully, completely read the page about how to ask support. In particular, most issues should first be discussed on the dedicated discussion group before introducing a bug report.