Mercurial > hg > orthanc-book

comparison Sphinx/source/developers/repositories.rst @ 340:b5741b354afa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bundles
author Sebastien Jodogne <s.jodogne@gmail.com>
date Thu, 26 Mar 2020 14:38:56 +0100
parents c0a3cd1cabff
children ab1ec4009541
comparison
equal deleted inserted replaced
339:c0a3cd1cabff 340:b5741b354afa
22 As pointed out on `Wikipedia 22 As pointed out on `Wikipedia
23 <https://en.wikipedia.org/wiki/Mercurial>`__, the *"Git vs. Mercurial 23 <https://en.wikipedia.org/wiki/Mercurial>`__, the *"Git vs. Mercurial
24 [debate] has become one of the holy wars of hacker culture."* We 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 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 26 Orthanc ecosystem. The fact is that a distributed revision-control
27 was needed for Orthanc, and that both Git and Mercurial have similar 27 was needed for Orthanc, and that both Git and Mercurial have a similar
28 set of features. 28 set of features.
29 29
30 If Orthanc were started in 2020, maybe we would have used Git, or 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 31 maybe not. But the Orthanc ecosystem is not at all about versioning
32 systems. We are entirely dedicated to lowering barriers to entry in 32 systems. We want to be entirely dedicated to lowering barriers to
33 the field of medical imaging. As a consequence, the choice of 33 entry in 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 34 Mercurial should be considered as a part of the history, and we simply
35 ask people to accept it as a fact. 35 ask people to accept it as a fact.
36 36
37 Regarding the reason behind self-hosting, Orthanc was hosted on 37 Regarding the reason behind self-hosting, Orthanc was hosted on
38 `Google Code 38 `Google Code
54 54
55 55
56 Accessing Mercurial 56 Accessing Mercurial
57 ------------------- 57 -------------------
58 58
59 .. _hg-clone:
60
59 Read-only access 61 Read-only access
60 ^^^^^^^^^^^^^^^^ 62 ^^^^^^^^^^^^^^^^
61 63
62 Anybody has full read-only access to all of the Orthanc official 64 Anybody has full read-only access to all of the Orthanc official
63 repositories, on our `self-hosted server 65 repositories, on our `self-hosted server
68 Locally cloning one of those Mercurial repositories (say, the main 70 Locally cloning one of those Mercurial repositories (say, the main
69 ``orthanc`` repository) is as simple as typing:: 71 ``orthanc`` repository) is as simple as typing::
70 72
71 $ hg clone https://hg.orthanc-server.com/orthanc 73 $ hg clone https://hg.orthanc-server.com/orthanc
72 74
75 You can then use separate tools such as `TortoiseHg
76 <https://en.wikipedia.org/wiki/TortoiseHg>`__ to browse the code with
77 richer features than the Web interface.
78
73 79
74 Write access 80 Write access
75 ^^^^^^^^^^^^ 81 ^^^^^^^^^^^^
76 82
77 Only the core developers of Orthanc have direct write access to the 83 Only the core developers of Orthanc have direct write access to the
78 Orthanc repositories (through SSH). 84 Orthanc repositories (through SSH).
79 85
86
87 .. _hg-contributing:
80 88
81 Submitting code 89 Submitting code
82 ^^^^^^^^^^^^^^^ 90 ^^^^^^^^^^^^^^^
83 91
84 We will of course be extremely grateful for receiving external code 92 We will of course be extremely grateful for receiving external code
85 contributions to the Orthanc repositories! 93 contributions to the Orthanc repositories!
86 94
87 However, one of the weaknesses of our self-hosted infrastructure is 95 However, one of the weaknesses of our self-hosted infrastructure is
88 that is does not support automation for `pull requests 96 that is does not support automation for `pull requests
89 <https://en.wikipedia.org/wiki/Distributed_version_control#Pull_requests>`__. 97 <https://en.wikipedia.org/wiki/Distributed_version_control#Pull_requests>`__.
90 This section explains two ways of contributing: by submitting a patch, 98 This section explains the `two accepted ways for communicating
91 or by providing a branch. 99 contributions
100 <https://www.mercurial-scm.org/wiki/CommunicatingChanges>`__: by
101 submitting a patch, or by exchanging a bundle.
92 102
93 Importantly, before any contribution can be accepted into the Orthanc 103 Importantly, before any contribution can be accepted into the Orthanc
94 repositories, its author must sign a :ref:`CLA <cla>`. This allows 104 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 105 both the University Hospital of Liège and the Osimis company to act as
96 the official guardians of the whole Orthanc ecosystem. 106 the official guardians of the whole Orthanc ecosystem.
97 107
98 108
99 Simple patch 109 .. _hg-patch:
100 ............ 110
111 Simple patch (import/export)
112 ............................
101 113
102 .. highlight:: bash 114 .. highlight:: bash
103 115
104 If you want to propose a simple contribution, the most direct way of 116 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**. 117 passing it on the Orthanc community is by creating a **simple patch**.
126 $ hg pull 138 $ hg pull
127 $ hg up -c default 139 $ hg up -c default
128 $ hg import /tmp/contribution.patch 140 $ hg import /tmp/contribution.patch
129 141
130 142
143 .. _hg-bundle:
131 144
132 Submitting a set of changes 145 Exchanging a bundle
133 ........................... 146 ...................
134 147
135 Work-in-progress. 148 .. highlight:: bash
149
150 If your contribution is made of several changesets (commits), you
151 should work in a dedicated branch, then submit a Mercurial bundle for
152 this branch.
136 153
154 First make sure to pull the latest version of the code repository,
155 then create a branch, say ``my-user/my-fix``, that derives from the
156 ``default`` branch (which corresponds to the mainline code)::
137 157
158 $ hg pull
159 $ hg up -c default
160 $ hg branch my-user/my-fix
161
162 WARNING: Please chose an unique, explicit name for your branch, and
163 make sure that your username is included within for traceability! The
164 name ``my-user/my-fix`` is only here for the purpose of the example.
165
166 You can then do all the modifications as required (including ``hg
167 add``, ``hg rm``, and ``hg commit``) in the branch
168 ``my-user/my-fix``. When you're done, create a Mercurial bundle that
169 gathers all your changes against the source repository as follows::
170
171 $ hg commit -m 'submitting my fix'
172 $ hg bundle /tmp/contribution.bundle https://hg.orthanc-server.com/orthanc
173
174 Obviously, make sure to replace
175 ``https://hg.orthanc-server.com/orthanc`` by the location of the
176 source repository.
177
178 Finally, you can submit the file ``/tmp/contribution.bundle`` to the
179 community, just like for simple patches. Note that this procedure
180 inherently corresponds to the manual creation of a pull request.
181
182 The core developers would reintegrate such a bundle into the mainline
183 by typing the following commands on their side::
184
185 $ cd /tmp
186 $ hg clone https://hg.orthanc-server.com/orthanc
187 $ cd /tmp/orthanc
188 $ hg unbundle /tmp/contribution.bundle
189 $ hg up -c default
190 $ hg merge my-user/my-fix
191
138 192
139 Issue tracker 193 Issue tracker
140 ------------- 194 -------------
141 195
142 This is work-in-progress. Orthanc will most probably move to the 196 This is work-in-progress. Orthanc will most probably move to the