Mercurial > hg > orthanc-book

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