Mercurial > hg > orthanc-book
annotate Sphinx/source/developers/repositories.rst @ 1110:16df49ed7981
documentation of option STL.3DHOP.CanvasStyle
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Fri, 04 Oct 2024 17:14:24 +0200 |
parents | 6814e5adb789 |
children |
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 |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
14 `self-hosted server <https://orthanc.uclouvain.be/hg/>`__. |
339
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 |
340 | 27 was needed for Orthanc, and that both Git and Mercurial have a similar |
339
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 |
340 | 31 maybe not. But the Orthanc ecosystem is not at all about versioning |
32 systems. We want to be entirely dedicated to lowering barriers to | |
33 entry in the field of medical imaging. As a consequence, the choice of | |
339
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 |
340 | 59 .. _hg-clone: |
60 | |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
61 Read-only access |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
62 ^^^^^^^^^^^^^^^^ |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
63 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
64 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
|
65 repositories, on our `self-hosted server |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
66 <https://orthanc.uclouvain.be/hg/>`__. As the ``hg serve`` tool that is |
390
32d0a95bee7e
note about slowness
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
366
diff
changeset
|
67 used by our Web server tends to be slow, we recommend people to |
32d0a95bee7e
note about slowness
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
366
diff
changeset
|
68 locally clone our Mercurial repositories. |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
69 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
70 .. highlight:: bash |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
71 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
72 Locally cloning one of those Mercurial repositories (say, the main |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
73 ``orthanc`` repository) is as simple as typing:: |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
74 |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
75 $ hg clone https://orthanc.uclouvain.be/hg/orthanc/ |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
76 |
340 | 77 You can then use separate tools such as `TortoiseHg |
78 <https://en.wikipedia.org/wiki/TortoiseHg>`__ to browse the code with | |
79 richer features than the Web interface. | |
80 | |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
81 |
391
4bc6bcd83ae5
hostfingerprints is not specific to Windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
390
diff
changeset
|
82 Recent versions of Mercurial |
4bc6bcd83ae5
hostfingerprints is not specific to Windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
390
diff
changeset
|
83 ............................ |
344 | 84 |
85 .. highlight:: text | |
86 | |
391
4bc6bcd83ae5
hostfingerprints is not specific to Windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
390
diff
changeset
|
87 While cloning the repository, you might face an error similar to:: |
344 | 88 |
89 abort: error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:661) | |
90 | |
91 In such a case, you must explicitly add the cryptographic fingerprint | |
391
4bc6bcd83ae5
hostfingerprints is not specific to Windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
390
diff
changeset
|
92 of our code server using a more recent option than the |
4bc6bcd83ae5
hostfingerprints is not specific to Windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
390
diff
changeset
|
93 ``hostfingerprints`` option. To this end, edit the `configuration file |
344 | 94 <https://www.mercurial-scm.org/doc/hgrc.5.html#files>`__ of Mercurial |
391
4bc6bcd83ae5
hostfingerprints is not specific to Windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
390
diff
changeset
|
95 (by default on Microsoft Windows, ``%USERPROFILE%\Mercurial.ini``), |
4bc6bcd83ae5
hostfingerprints is not specific to Windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
390
diff
changeset
|
96 and add the following lines:: |
344 | 97 |
98 [hostsecurity] | |
1029
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
99 orthanc.uclouvain.be:fingerprints=sha256:30:1d:d8:b6:a2:50:23:6a:a1:b7:da:66:b6:aa:2f:fa:59:f3:9d:cd:ed:f8:2c:49:14:57:25:39:84:b9:60:db |
344 | 100 |
101 .. highlight:: bash | |
102 | |
103 For reference, here is the command that was used to generate this | |
514
55bd72f6df8a
update mercurial fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
498
diff
changeset
|
104 SHA256 fingerprint (`click here for more information |
344 | 105 <https://stackoverflow.com/a/56579497/881731>`__):: |
106 | |
1029
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
107 $ openssl s_client -servername orthanc.uclouvain.be -connect orthanc.uclouvain.be:443 \ |
522 | 108 < /dev/null 2>/dev/null | openssl x509 -fingerprint -sha256 -noout -in /dev/stdin |
344 | 109 |
1029
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
110 **Important:** As our certificates are changed periodically, you'll |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
111 have to regularly update your configuration file once Mercurial |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
112 complains about an unexpected fingerprint. |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
113 |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
114 |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
115 Old versions of Mercurial |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
116 ^^^^^^^^^^^^^^^^^^^^^^^^^ |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
117 |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
118 .. highlight:: text |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
119 |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
120 For old versions of Mercurial that do not support SHA256, add the |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
121 following lines to your ``~/.hgrc`` file:: |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
122 |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
123 [hostfingerprints] |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
124 orthanc.uclouvain.be = 69:C0:EF:E7:05:BB:2A:0B:88:EA:E8:00:C6:1A:95:A3:53:74:C1:D4 |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
125 |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
126 .. highlight:: bash |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
127 |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
128 For reference, here is the command that was used to generate this SHA1 |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
129 fingerprint (`click here for more information |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
130 <https://wiki.fluidproject.org/display/fluid/Setting+Host+Fingerprints+for+Mercurial>`__):: |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
131 |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
132 $ openssl s_client -servername orthanc.uclouvain.be -connect orthanc.uclouvain.be:443 \ |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
133 < /dev/null 2>/dev/null | openssl x509 -fingerprint -sha1 -noout -in /dev/stdin |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
134 |
344 | 135 |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
136 Write access |
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 Only the core developers of Orthanc have direct write access to the |
342 | 140 Orthanc repositories (through SSH). Core developers can clone a |
141 repository with write access as follows:: | |
142 | |
993
05b106383b2a
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
991
diff
changeset
|
143 $ hg clone ssh://hg@orthanc.uclouvain.be/public/orthanc/ |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
144 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
145 |
340 | 146 .. _hg-contributing: |
147 | |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
148 Submitting code |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
149 ^^^^^^^^^^^^^^^ |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
150 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
151 We will of course be extremely grateful for receiving external code |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
152 contributions to the Orthanc repositories! |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
153 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
154 However, one of the weaknesses of our self-hosted infrastructure is |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
155 that is does not support automation for `pull requests |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
156 <https://en.wikipedia.org/wiki/Distributed_version_control#Pull_requests>`__. |
340 | 157 This section explains the `two accepted ways for communicating |
158 contributions | |
159 <https://www.mercurial-scm.org/wiki/CommunicatingChanges>`__: by | |
160 submitting a patch, or by exchanging a bundle. | |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
161 |
627 | 162 |
1032
6814e5adb789
end of dual licensing and cla
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1029
diff
changeset
|
163 .. _code_quality: |
6814e5adb789
end of dual licensing and cla
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1029
diff
changeset
|
164 |
627 | 165 Code quality |
166 ............ | |
167 | |
168 * Your code **must follow the C++03 standard** (C++11 is not accepted | |
169 for maximum cross-platform compatibility on older platforms). | |
170 | |
1004
17bf6fafb884
added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
993
diff
changeset
|
171 * The continuous integration servers at UCLouvain check that Orthanc |
627 | 172 properly compiles on Ubuntu 16.04, on `Linux Standard Base systems |
173 <https://refspecs.linuxfoundation.org/lsb.shtml>`__ using the `LSB | |
174 SDB 5.0.0 | |
175 <http://ftp.linuxfoundation.org/pub/lsb/bundles/released-5.0.0/sdk/>`__, | |
176 on FreeBSD, on Microsoft Visual Studio 2008 (32 bit), on Microsoft | |
177 Visual Studio 2015 (64 bit), and on Apple OS X 10.9 | |
178 "Mavericks". Submitted code might have to be adapted to compile on | |
179 these platforms. Architecture-dependant code should be located in | |
180 the `Orthanc::Toolbox | |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
181 <https://orthanc.uclouvain.be/hg/orthanc/file/default/OrthancFramework/Sources/Toolbox.h>`__ |
627 | 182 and `Orthanc::SystemToolbox |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
183 <https://orthanc.uclouvain.be/hg/orthanc/file/default/OrthancFramework/Sources/SystemToolbox.h>`__ |
627 | 184 static classes. |
185 | |
186 * Please stick to the :ref:`coding style <coding-style>` of Orthanc. | |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
187 |
627 | 188 * Your individual contributions should be kept **as small as |
189 possible**, and should be focused on one very specific issue or | |
190 feature. Large architectural changes are reserved for the core | |
191 development team of Orthanc, as we must follow our `long-term | |
192 roadmap | |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
193 <https://orthanc.uclouvain.be/hg/orthanc/file/default/TODO>`__. |
627 | 194 |
195 * Unit testing is mandatory. Integration tests should be submitted to | |
196 the `dedicated repository | |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
197 <https://orthanc.uclouvain.be/hg/orthanc-tests/file/default>`__. |
627 | 198 |
199 * All the contributions will be carefully reviewed. Some contributions | |
200 may be modified, yet even rejected. A rejection might for instance | |
201 occur if your contribution does not match the Orthanc roadmap, does | |
202 not meet our high-quality code standards, or breaks backward | |
203 compatibility. Please be sure that we warmly welcome and appreciate | |
204 your contributions, but be aware of the fact that we are quite | |
205 strict, and that the review process might take time. This is why the | |
206 recommended way of contributing to Orthanc is always by | |
207 :ref:`creating contributed plugins <creating-plugins>`. | |
208 | |
1029
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
209 * If intellectual property is of importance to you, make sure to |
968
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
210 carefully read our :ref:`FAQ about the licensing of submitted code |
1029
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
211 <submitting_code>`. If you are concerned about intellectual |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
212 property, consider creating plugins instead of submitting code |
c819a8138cad
updated host fingerprints
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
213 directly to the core project. |
361 | 214 |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
215 |
340 | 216 .. _hg-patch: |
217 | |
218 Simple patch (import/export) | |
219 ............................ | |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
220 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
221 .. highlight:: bash |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
222 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
223 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
|
224 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
|
225 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
226 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
|
227 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
|
228 mainline code):: |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
229 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
230 $ hg pull |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
231 $ hg up -c default |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
232 [...make your modifications...] |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
233 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
234 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
|
235 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
236 $ hg export -r default > /tmp/contribution.patch |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
237 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
238 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
|
239 file to the Orthanc community, e.g. by submitting it onto our official |
984
46e2941b57dd
replace link to google users group by link to discourse
Alain Mazy <am@osimis.io>
parents:
968
diff
changeset
|
240 `Orthanc Users discussion forum |
46e2941b57dd
replace link to google users group by link to discourse
Alain Mazy <am@osimis.io>
parents:
968
diff
changeset
|
241 <https://discourse.orthanc-server.org>`__. The core |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
242 developers would reintegrate such a patch by typing the following |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
243 command on their side:: |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
244 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
245 $ hg pull |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
246 $ hg up -c default |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
247 $ hg import /tmp/contribution.patch |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
248 |
558
8d6e94423004
dos2unix in hg import
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
548
diff
changeset
|
249 NB: If the ``hg export`` command was run on Microsoft Windows, one |
8d6e94423004
dos2unix in hg import
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
548
diff
changeset
|
250 might have to convert the end-of-lines from DOS (CR/LF) to UNIX (LF |
559 | 251 only) using the ``dos2unix`` command on the patch file, before running |
252 ``hg import``. Otherwise, errors like ``Hunk #1 FAILED`` might show | |
253 up. | |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
254 |
558
8d6e94423004
dos2unix in hg import
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
548
diff
changeset
|
255 |
340 | 256 .. _hg-bundle: |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
257 |
340 | 258 Exchanging a bundle |
259 ................... | |
260 | |
261 .. highlight:: bash | |
262 | |
263 If your contribution is made of several changesets (commits), you | |
264 should work in a dedicated branch, then submit a Mercurial bundle for | |
265 this branch. | |
266 | |
267 First make sure to pull the latest version of the code repository, | |
268 then create a branch, say ``my-user/my-fix``, that derives from the | |
269 ``default`` branch (which corresponds to the mainline code):: | |
270 | |
271 $ hg pull | |
272 $ hg up -c default | |
273 $ hg branch my-user/my-fix | |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
274 |
340 | 275 WARNING: Please chose an unique, explicit name for your branch, and |
276 make sure that your username is included within for traceability! The | |
277 name ``my-user/my-fix`` is only here for the purpose of the example. | |
278 | |
279 You can then do all the modifications as required (including ``hg | |
280 add``, ``hg rm``, and ``hg commit``) in the branch | |
281 ``my-user/my-fix``. When you're done, create a Mercurial bundle that | |
282 gathers all your changes against the source repository as follows:: | |
283 | |
284 $ hg commit -m 'submitting my fix' | |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
285 $ hg bundle /tmp/contribution.bundle https://orthanc.uclouvain.be/hg/orthanc |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
286 |
340 | 287 Obviously, make sure to replace |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
288 ``https://orthanc.uclouvain.be/hg/orthanc`` by the location of the |
340 | 289 source repository. |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
290 |
340 | 291 Finally, you can submit the file ``/tmp/contribution.bundle`` to the |
292 community, just like for simple patches. Note that this procedure | |
293 inherently corresponds to the manual creation of a pull request. | |
294 | |
295 The core developers would reintegrate such a bundle into the mainline | |
296 by typing the following commands on their side:: | |
297 | |
298 $ cd /tmp | |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
299 $ hg clone https://orthanc.uclouvain.be/hg/orthanc/ |
340 | 300 $ cd /tmp/orthanc |
301 $ hg unbundle /tmp/contribution.bundle | |
302 $ hg up -c default | |
303 $ hg merge my-user/my-fix | |
968
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
304 |
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
305 |
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
306 .. _hg-submitting: |
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
307 |
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
308 Submitting contributions |
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
309 ........................ |
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
310 |
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
311 Contributed patches and bundles must be sent by e-mail, either to |
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
312 `Sébastien Jodogne <mailto:sebastien.jodogne@uclouvain.be>`__ |
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
313 (UCLouvain) or to `Alain Mazy <mailto:am@orthanc.team>`__ (Orthanc |
4ce37a89b212
Submitting contributions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
844
diff
changeset
|
314 Team). |
340 | 315 |
339
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
316 |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
317 Issue tracker |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
318 ------------- |
c0a3cd1cabff
Accessing code repositories
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
319 |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
320 The `official bug tracker <https://orthanc.uclouvain.be/bugs/>`__ of the |
445
987fbbc2b59e
leaving bitbucket wrt. bug tracker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
436
diff
changeset
|
321 Orthanc project runs thanks to `Bugzilla |
987fbbc2b59e
leaving bitbucket wrt. bug tracker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
436
diff
changeset
|
322 <https://en.wikipedia.org/wiki/Bugzilla>`__. |
987fbbc2b59e
leaving bitbucket wrt. bug tracker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
436
diff
changeset
|
323 |
987fbbc2b59e
leaving bitbucket wrt. bug tracker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
436
diff
changeset
|
324 We have done our best to automatically import most of the history |
987fbbc2b59e
leaving bitbucket wrt. bug tracker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
436
diff
changeset
|
325 from the old BitBucket bug tracker. |
987fbbc2b59e
leaving bitbucket wrt. bug tracker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
436
diff
changeset
|
326 |
987fbbc2b59e
leaving bitbucket wrt. bug tracker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
436
diff
changeset
|
327 Before posting any issue, make sure to carefully, completely read the |
987fbbc2b59e
leaving bitbucket wrt. bug tracker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
436
diff
changeset
|
328 :ref:`page about how to ask support <support>`. In particular, most |
984
46e2941b57dd
replace link to google users group by link to discourse
Alain Mazy <am@osimis.io>
parents:
968
diff
changeset
|
329 issues should first be discussed on the dedicated `Orthanc Users discussion forum |
46e2941b57dd
replace link to google users group by link to discourse
Alain Mazy <am@osimis.io>
parents:
968
diff
changeset
|
330 <https://discourse.orthanc-server.org>`__ before |
445
987fbbc2b59e
leaving bitbucket wrt. bug tracker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
436
diff
changeset
|
331 introducing a bug report. |