source: utils/dev/README.rst @ 11705

Last change on this file since 11705 was 10655, checked in by nicolasmartin, 22 months ago

Updating of dev. guide + review of install_dev_env.sh to be a bit more specific in its checkout

File size: 11.6 KB
Line 
1**********************************
2Developer guide for SVN operations
3**********************************
4
5.. contents::
6    :depth: 1
7
8Source code organisation
9========================
10
11Building from several checkouts
12-------------------------------
13
14| As of now, the NEMO code is build from different sources in the repository,
15  via SVN external definitions which are special versioned properties specified on its sub-items
16  (folders and file).
17| For more, read `the documentation on external definitions in ​the SVN book
18  <http://svnbook.red-bean.com/en/1.7/svn.advanced.externals.html>`_.
19
20On one hand, the *core code*, which is actively developed from one release to another,
21is still present and unique for a branch.
22
23:./cfgs:  Reference configurations
24:./doc:   Reference manuals (LaTeX) and user guide (reStructuredText)
25:./src:   Modelling routines
26:./tests: Test cases
27
28| On the other hand,
29  the *complementary code*, defined by minor modifications between consecutive releases,
30  is managed apart from the default development organisation
31  (``branches``, ``releases``, `tags` and ``trunk``).
32| It has been extracted to another locations in the repository and
33  can considered from now on as external sources.
34
35:./arch:     Settings for computing architecture
36:./ext:      External dependencies
37             (AGRIF for nesting, FCM for compilation and IOIPSL for IO)
38:./makenemo: Script for building NEMO executable
39:./mk:       Compilation sub-scripts
40:./tools:    User tools
41
42.. note::
43
44    The major benefit of this implementation is the convenient way of sharing code.
45    Part of the source code can be develop in one location, in-house or externally,
46    and distribute to several working copies.
47
48External sources in working copy
49--------------------------------
50
51Here is the current list of these externals for the NEMO code:
52
53.. code:: sh
54
55    # Relative URL                         Item
56    # '^': alias for repository root
57    ^/utils/build/arch@{HEAD,${REV}}       arch
58    ^/utils/build/makenemo@{HEAD,${REV}}   makenemo
59    ^/utils/build/mk@{HEAD,${REV}}         mk
60    ^/utils/tools@{HEAD,${REV}}            tools
61    ^/vendors/AGRIF/dev@{HEAD,${REV}}      ext/AGRIF
62    ^/vendors/FCM@{HEAD,${REV}}            ext/FCM
63    ^/vendors/IOIPSL@{HEAD,${REV}}         ext/IOIPSL
64
65.. important::
66
67    Regarding the main branches of NEMO development,
68    official releases and tagged snapshots will have fixed externals,
69    however the trunk will always refer to the ``HEAD`` of the repository.
70
71.. note::
72
73    | As we cannot add comments in the context of versioned properties,
74      the revision number of an external source could be a major information
75      for those would starting to scrutinize the code.
76    | Revision changes have to be limited it to what is strictly necessary,
77      i.e. only for the external(s) at stake, and
78      each definition must refer to an effective revision considered as reliable.
79
80Developer perspective
81---------------------
82
83| The external definitions are retained by branching operations so in the first place
84  a development branch created from the trunk will update its external sources to the latest.
85| From that the developer makes a choice for each external in the development branch
86
87+--------------------------+---------------------------------------------------------+
88| *Set explicit revision*  | Isolated from unwanted commits                          |
89|                          |                                                         |
90|                          | Get back to or reproduce confidently a previous version |
91+--------------------------+---------------------------------------------------------+
92| *Keep ``HEAD`` revision* | Modify directly the external and receive all updates    |
93|                          |                                                         |
94|                          | No commit record in the meantime                        |
95+--------------------------+---------------------------------------------------------+
96
97| Due to different attributes exposed above,
98  **it is strongly recommended to set explicit revisions on externals for a development branch**.
99| Nevertheless the developer can have its reasons to have implicit revision for given item(s) and
100  can update the definitions on a case-by-case basis.
101
102The SVN commands for managing external definitions are below,
103modified externals are reported in the 2 :sup:`nd` column of ``svn {st,status}`` output.
104
105.. code:: sh
106
107    ## Get the current definitions
108    $ svn propget   svn:externals ${PATH}
109
110    ## Edit them in external editor (SVN_EDITOR env. variable)
111    $ svn propedit  svn:externals ${PATH}
112
113.. warning::
114
115    Think about committing your new definitions
116
117Recommended development environment
118===================================
119
120Lightweight repository copy
121---------------------------
122
123.. |download| replace:: **download**
124.. _download: https://forge.ipsl.jussieu.fr/nemo/export/HEAD/utils/dev/install_dev_env.sh
125
126Although each developer can have its own approach for developing the NEMO source code,
127**we recommend to** |download|_ **and run** ``install_dev_env.sh`` **script to
128set up a clean and minimal environment**.
129From there, the developer would be able to start his developments but
130also to support the NEMO shared reference in the same working copy.
131
132| Actually the script will checkout the repository in a slightly different manner from the usual way,
133  using the ``--depth`` and ``--set-depth`` SVN options in order to
134  download the sub-paths of the default development organisation in various depths
135  (``branches``, ``releases``, ``tags`` and ``trunk``).
136| In the end, the developer will have a versioned copy of the repository first levels with empty folders,
137  except for the `trunk` (``/NEMO/trunk``) and the last official release (``/NEMO/releases/release-X.X``)
138  which have been fully downloaded.
139
140The benefits of this new approach are numerous
141
142- **Possibility to work offline like git**:
143  create a development branch by copying the `trunk` locally and
144  start coding without a first commit to the remote repository,
145  instead of creating the development branch remotely on the repository,
146  then downloading it to begin to work.
147- **Simple UNIX-like syntax for SVN commands** (``svn {add,cat,cp,ls,mv,rm} ...``) and
148  no more tedious URL scheme to use (``svn+ssh://...``).
149- **All developments handled in one common location** by
150  putting an end at the branches scattering with several isolated working copies
151  (usually one single checkout per branch).
152
153Examples
154--------
155
156Usage of ``install_dev_env.sh``
157^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
158.. code:: console
159
160    $ ./install_dev_env.sh [${DEVELOPER_ID} [repo]]
161
162Positional arguments in option
163
1641. ``DEVELOPER_ID``: configure the working copy in developer mode,
165   i.e. URL in ``svn info`` begins with |DEV_URL| ... instead of |URL|,
166   so the developer can commit to the repository right away
167   (switching can be made later if needed).
1682. ``repo``: download the whole layout of the repository instead of the default development organisation
169   to manage the development of the sources used as externals.
170   By default,
171   the checkout is from root directory ``/NEMO`` with ``branches``, ``releases``, ``tags`` and ``trunk``.
172   With ``repo`` argument, it does from the root of repository with ``/NEMO``, ``/utils``, ``/vendors``.
173
174Create a branch
175^^^^^^^^^^^^^^^
176
177.. code:: console
178
179    $ svn copy {${URL_SRC},${PATH_SRC}}[@${REV}] {${URL_DST},${PATH_DST}}
180
181+------------------+--------------------------------------------------------------------+-----------------------------------------------+
182|  local -> local  | ``PATH_SRC`` = ``trunk``                                           | *Copy unversioned items to the new branch*    |
183|                  |                                                                    |                                               |
184|                  | ``PATH_DST`` = ``branches/${YEAR}/${BRANCH_NAME}``                 |                                               |
185+------------------+--------------------------------------------------------------------+-----------------------------------------------+
186|  local -> remote | ``PATH_SRC`` = ``trunk``                                           | *New branch created only in the repository*   |
187|                  |                                                                    |                                               |
188|                  | ``URL_DST``  = ``${DEV_URL}/NEMO/branches/${YEAR}/${BRANCH_NAME}`` |                                               |
189+------------------+--------------------------------------------------------------------+-----------------------------------------------+
190| remote -> local  | ``URL_SRC``  = ``${URL}/NEMO/trunk``                               | *Clean copy of the trunk from the repository* |
191|                  |                                                                    |                                               |
192|                  | ``PATH_DST`` = ``branches/${YEAR}/${BRANCH_NAME}``                 |                                               |
193+------------------+--------------------------------------------------------------------+-----------------------------------------------+
194| remote -> remote | ``URL_SRC``  = ``${URL}/NEMO/trunk``                               | *All done on server side*                     |
195|                  |                                                                    |                                               |
196|                  | ``URL_DST``  = ``${DEV_URL}/NEMO/branches/${YEAR}/${BRANCH_NAME}`` |                                               |
197+------------------+--------------------------------------------------------------------+-----------------------------------------------+
198
199.. |URL|      replace:: ``http://forge.ipsl.jussieu.fr/nemo/svn``
200.. |DEV_URL|  replace:: ``svn+ssh://${DEVELOPER_ID}@forge.ipsl.jussieu.fr/ipsl/forge/projets/nemo/svn``
201
202.. note::
203
204    | ``URL``     = |URL|
205    | ``DEV_URL`` = |DEV_URL|
206
207    | Usual convention for the naming of the development branches:
208    | ``BRANCH_NAME`` = ``dev_r${TRUNK_REVISION_ON_FORK}_${ACTION_NAME_IN_WORKPLAN}``
209
210
211Download a branch from the repository
212^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
213
214.. code:: console
215
216    List the remote branches in the repository
217    $ svn ls branches/${YEAR}
218
219    Download the one chosen
220    $ svn update branches/${YEAR}/${BRANCH_NAME}
221
222Delete the local copy of a branch
223^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
224
225.. code:: console
226
227    Set branch depth to 'exclude'
228    => Tag the branch as to be deleted
229    $ svn update --set-depth exclude branches/${YEAR}/${BRANCH_NAME}
230    D    dev_r....
231
232    Effective removal
233    $ svn update branches/${YEAR}
234
235Working smart with available resources
236======================================
237
238Make link between commit and ticket(s)
239--------------------------------------
240
241If a commit is related to ticket(s), we highly suggest to mention it in the commit log message:
242
243  - the commit will be converted into a comment in the ticket thread(s)
244  - URL link(s) to selected ticket(s) will be provided in the email notification and the changeset page.
245
246| To do so,
247  you can use a word from this list ``addresses re references refs see`` followed by usual ticket link(s).
248| For instance
249
250.. code:: console
251
252    $ svn commit -m '[...] see #${TICKET_ID} [...]'
253
254Close ticket(s) when committing
255-------------------------------
256
257| If a commit is a fix,
258  you can close targeted ticket(s) with the commit operation without the need of a browser.
259| For this,
260  you can use a word from the list ``close closed closes fix fixed fixes`` followed by usual ticket link(s).
261| For instance
262
263.. code:: console
264
265    $ svn commit -m '[...] fix #${TICKET_ID} [...]'
Note: See TracBrowser for help on using the repository browser.