Accessing code repositories¶

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:13:CA:46:BB:84:96:BD:D4:F7:09:94:60:0F:C2:3B:BA:87:E2:33:50:75:ED:0A:44:81:DF:80:EB:44:6B:C5:40

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

Code quality¶

• Your code must follow the C++03 standard (C++11 is not accepted for maximum cross-platform compatibility on older platforms).
• The continuous integration servers of Osimis check that Orthanc properly compiles on Ubuntu 16.04, on Linux Standard Base systems using the LSB SDB 5.0.0, on FreeBSD, on Microsoft Visual Studio 2008 (32 bit), on Microsoft Visual Studio 2015 (64 bit), and on Apple OS X 10.9 “Mavericks”. Submitted code might have to be adapted to compile on these platforms. Architecture-dependant code should be located in the Orthanc::Toolbox and Orthanc::SystemToolbox static classes.
• Please stick to the coding style of Orthanc.
• Your individual contributions should be kept as small as possible, and should be focused on one very specific issue or feature. Large architectural changes are reserved for the core development team of Orthanc, as we must follow our long-term roadmap.
• Unit testing is mandatory. Integration tests should be submitted to the dedicated repository.
• All the contributions will be carefully reviewed. Some contributions may be modified, yet even rejected. A rejection might for instance occur if your contribution does not match the Orthanc roadmap, does not meet our high-quality code standards, or breaks backward compatibility. Please be sure that we warmly welcome and appreciate your contributions, but be aware of the fact that we are quite strict, and that the review process might take time. This is why the recommended way of contributing to Orthanc is always by creating contributed plugins.
• Importantly, before any contribution can be accepted into the Orthanc repositories, its author must sign a CLA. This allows the University Hospital of Liège, the Osimis company and UCLouvain university to act as the official guardians of the whole Orthanc ecosystem. Another advantage of creating plugins is that signing a CLA is not needed. Make sure to carefully read our FAQ about the licensing of submitted 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

NB: If the hg export command was run on Microsoft Windows, one might have to convert the end-of-lines from DOS (CR/LF) to UNIX (LF only) using the dos2unix command on the patch file, before running hg import. Otherwise, errors like Hunk #1 FAILED might show up.

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