Mercurial > hg > orthanc-book

comparison Sphinx/source/developers/repositories.rst @ 339:c0a3cd1cabff

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Accessing code repositories
author Sebastien Jodogne <s.jodogne@gmail.com>
date Thu, 26 Mar 2020 13:32:08 +0100
parents
children b5741b354afa
comparison
equal deleted inserted replaced
338:93581ca92c6a 339:c0a3cd1cabff
1 .. _repositories:
2
3 Accessing code repositories
4 ===========================
5
6 .. contents::
7
8
9 Context
10 -------
11
12 The Orthanc server and most of its plugins are versioned using
13 `Mercurial <https://en.wikipedia.org/wiki/Mercurial>`__ on a
14 `self-hosted server <https://hg.orthanc-server.com/>`__.
15
16 The Orthanc project started back in 2011, back in a time where
17 Mercurial and `Git <https://en.wikipedia.org/wiki/Git>`__ were equally
18 popular. Sébastien Jodogne, the original author of Orthanc, decided to
19 use Mercurial given the higher simplicity of its set of commands, and
20 given the fact it is safer to use for less experienced users.
21
22 As pointed out on `Wikipedia
23 <https://en.wikipedia.org/wiki/Mercurial>`__, the *"Git vs. Mercurial
24 [debate] has become one of the holy wars of hacker culture."* We
25 certainly don't want to endure this debate in the context of the
26 Orthanc ecosystem. The fact is that a distributed revision-control
27 was needed for Orthanc, and that both Git and Mercurial have similar
28 set of features.
29
30 If Orthanc were started in 2020, maybe we would have used Git, or
31 maybe not. But the Orthanc ecosystem is not about versioning
32 systems. We are entirely dedicated to lowering barriers to entry in
33 the field of medical imaging. As a consequence, the choice of
34 Mercurial should be considered as a part of the history, and we simply
35 ask people to accept it as a fact.
36
37 Regarding the reason behind self-hosting, Orthanc was hosted on
38 `Google Code
39 <https://en.wikipedia.org/wiki/Google_Developers#Google_Code>`__
40 between 2012 and 2015, until it was shutdown. In July 2015, Orthanc
41 was moved to `Bitbucket by Atlassian
42 <https://en.wikipedia.org/wiki/Bitbucket>`__. Unfortunately, in July
43 2019, Bitbucket announced that `Mercurial support would be dropped on
44 June 2020
45 <https://bitbucket.org/blog/sunsetting-mercurial-support-in-bitbucket>`__,
46 forcing us to deal with another migration.
47
48 We are of course grateful to Google and Atlassian for having hosted
49 Orthanc during 8 years. However, we cannot afford the cost of
50 periodically coping with hosting migrations. We prefer to have a
51 simpler environment, yet under our full control. As a consequence,
52 starting Q2 2020, Orthanc is hosted using the official ``hg serve``
53 tool.
54
55
56 Accessing Mercurial
57 -------------------
58
59 Read-only access
60 ^^^^^^^^^^^^^^^^
61
62 Anybody has full read-only access to all of the Orthanc official
63 repositories, on our `self-hosted server
64 <https://hg.orthanc-server.com/>`__.
65
66 .. highlight:: bash
67
68 Locally cloning one of those Mercurial repositories (say, the main
69 ``orthanc`` repository) is as simple as typing::
70
71 $ hg clone https://hg.orthanc-server.com/orthanc
72
73
74 Write access
75 ^^^^^^^^^^^^
76
77 Only the core developers of Orthanc have direct write access to the
78 Orthanc repositories (through SSH).
79
80
81 Submitting code
82 ^^^^^^^^^^^^^^^
83
84 We will of course be extremely grateful for receiving external code
85 contributions to the Orthanc repositories!
86
87 However, one of the weaknesses of our self-hosted infrastructure is
88 that is does not support automation for `pull requests
89 <https://en.wikipedia.org/wiki/Distributed_version_control#Pull_requests>`__.
90 This section explains two ways of contributing: by submitting a patch,
91 or by providing a branch.
92
93 Importantly, before any contribution can be accepted into the Orthanc
94 repositories, its author must sign a :ref:`CLA <cla>`. This allows
95 both the University Hospital of Liège and the Osimis company to act as
96 the official guardians of the whole Orthanc ecosystem.
97
98
99 Simple patch
100 ............
101
102 .. highlight:: bash
103
104 If you want to propose a simple contribution, the most direct way of
105 passing it on the Orthanc community is by creating a **simple patch**.
106
107 First make sure to pull the latest version of the code repository,
108 then work on your modification in the ``default`` branch (i.e. in the
109 mainline code)::
110
111 $ hg pull
112 $ hg up -c default
113 [...make your modifications...]
114
115 Once your contribution is done, here is how to export a patch::
116
117 $ hg export -r default > /tmp/contribution.patch
118
119 Once the patch is ready, you can send the ``/tmp/contribution.patch``
120 file to the Orthanc community, e.g. by submitting it onto our official
121 `discussion group
122 <https://groups.google.com/forum/#!forum/orthanc-users>`__. The core
123 developers would reintegrate such a patch by typing the following
124 command on their side::
125
126 $ hg pull
127 $ hg up -c default
128 $ hg import /tmp/contribution.patch
129
130
131
132 Submitting a set of changes
133 ...........................
134
135 Work-in-progress.
136
137
138
139 Issue tracker
140 -------------
141
142 This is work-in-progress. Orthanc will most probably move to the
143 `Roundup issue tracker
144 <https://en.wikipedia.org/wiki/Roundup_(issue_tracker)>`__ that is
145 notably used by the Python community.