Mercurial > hg > orthanc-book
comparison Sphinx/source/developers/repositories.rst @ 339:c0a3cd1cabff
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. |