# HG changeset patch # User Sebastien Jodogne # Date 1585225928 -3600 # Node ID c0a3cd1cabfff4d327d10454abe0b016ea51425c # Parent 93581ca92c6ae769f1cf4408b09952e2c3e3e216 Accessing code repositories diff -r 93581ca92c6a -r c0a3cd1cabff Sphinx/source/developers.rst --- a/Sphinx/source/developers.rst Thu Mar 19 09:46:02 2020 +0100 +++ b/Sphinx/source/developers.rst Thu Mar 26 13:32:08 2020 +0100 @@ -4,8 +4,10 @@ .. toctree:: :maxdepth: 1 + developers/repositories.rst developers/creating-plugins.rst developers/stone.rst developers/db-versioning.rst developers/implementation-notes.rst developers/coding-style.rst + diff -r 93581ca92c6a -r c0a3cd1cabff Sphinx/source/developers/repositories.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/developers/repositories.rst Thu Mar 26 13:32:08 2020 +0100 @@ -0,0 +1,145 @@ +.. _repositories: + +Accessing code repositories +=========================== + +.. contents:: + + +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 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 about versioning +systems. We are 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 +`__. + +.. highlight:: bash + +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 + + +Write access +^^^^^^^^^^^^ + +Only the core developers of Orthanc have direct write access to the +Orthanc repositories (through SSH). + + +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 two ways of contributing: by submitting a patch, +or by providing a branch. + +Importantly, before any contribution can be accepted into the Orthanc +repositories, its author must sign a :ref:`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. + + +Simple patch +............ + +.. highlight:: bash + +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 + + + +Submitting a set of changes +........................... + +Work-in-progress. + + + +Issue tracker +------------- + +This is work-in-progress. Orthanc will most probably move to the +`Roundup issue tracker +`__ that is +notably used by the Python community.