source: utils/dev/README.rst @ 10649

Last change on this file since 10649 was 10649, checked in by nicolasmartin, 18 months ago

Import a developer guide to help on operations with the repository

  • Explanation on the new organisation of the repository with the use of SVN external definitions
  • Provide few examples for install_dev_env.sh script and branching cmds under

the recommended development environment

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