[10649] | 1 | ********************************** |
---|
| 2 | Developer guide for SVN operations |
---|
| 3 | ********************************** |
---|
| 4 | |
---|
| 5 | .. contents:: |
---|
| 6 | :depth: 1 |
---|
| 7 | |
---|
| 8 | Source code organisation |
---|
| 9 | ======================== |
---|
| 10 | |
---|
| 11 | Building from several checkouts |
---|
| 12 | ------------------------------- |
---|
| 13 | |
---|
[10655] | 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). |
---|
[10649] | 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 | |
---|
[10655] | 20 | On one hand, the *core code*, which is actively developed from one release to another, |
---|
| 21 | is still present and unique for a branch. |
---|
[10649] | 22 | |
---|
| 23 | :./cfgs: Reference configurations |
---|
| 24 | :./doc: Reference manuals (LaTeX) and user guide (reStructuredText) |
---|
| 25 | :./src: Modelling routines |
---|
| 26 | :./tests: Test cases |
---|
| 27 | |
---|
[10655] | 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. |
---|
[10649] | 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 | |
---|
[10655] | 42 | .. note:: |
---|
[10649] | 43 | |
---|
[10655] | 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 | |
---|
[10649] | 48 | External sources in working copy |
---|
| 49 | -------------------------------- |
---|
| 50 | |
---|
| 51 | Here 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 | |
---|
[10655] | 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. |
---|
[10649] | 70 | |
---|
[10655] | 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 | |
---|
[10649] | 80 | Developer perspective |
---|
| 81 | --------------------- |
---|
| 82 | |
---|
[10655] | 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 |
---|
[10649] | 86 | |
---|
[10655] | 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 | +--------------------------+---------------------------------------------------------+ |
---|
[10649] | 96 | |
---|
[10655] | 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. |
---|
[10649] | 101 | |
---|
[10655] | 102 | The SVN commands for managing external definitions are below, |
---|
| 103 | modified externals are reported in the 2 :sup:`nd` column of ``svn {st,status}`` output. |
---|
[10649] | 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 | |
---|
[10655] | 115 | Think about committing your new definitions |
---|
[10649] | 116 | |
---|
| 117 | Recommended development environment |
---|
| 118 | =================================== |
---|
| 119 | |
---|
| 120 | Lightweight 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 | |
---|
| 126 | Although 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 |
---|
| 128 | set up a clean and minimal environment**. |
---|
| 129 | From there, the developer would be able to start his developments but |
---|
| 130 | also 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 |
---|
[10655] | 134 | download the sub-paths of the default development organisation in various depths |
---|
| 135 | (``branches``, ``releases``, ``tags`` and ``trunk``). |
---|
[10649] | 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 | |
---|
[10655] | 140 | The benefits of this new approach are numerous |
---|
[10649] | 141 | |
---|
| 142 | - **Possibility to work offline like git**: |
---|
[10655] | 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. |
---|
[10649] | 147 | - **Simple UNIX-like syntax for SVN commands** (``svn {add,cat,cp,ls,mv,rm} ...``) and |
---|
[10655] | 148 | no more tedious URL scheme to use (``svn+ssh://...``). |
---|
[10649] | 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 | |
---|
| 153 | Examples |
---|
| 154 | -------- |
---|
| 155 | |
---|
| 156 | Usage of ``install_dev_env.sh`` |
---|
| 157 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
| 158 | .. code:: console |
---|
| 159 | |
---|
| 160 | $ ./install_dev_env.sh [${DEVELOPER_ID} [repo]] |
---|
| 161 | |
---|
| 162 | Positional arguments in option |
---|
| 163 | |
---|
| 164 | 1. ``DEVELOPER_ID``: configure the working copy in developer mode, |
---|
| 165 | i.e. URL in ``svn info`` begins with |DEV_URL| ... instead of |URL|, |
---|
[10655] | 166 | so the developer can commit to the repository right away |
---|
| 167 | (switching can be made later if needed). |
---|
| 168 | 2. ``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``. |
---|
[10649] | 172 | With ``repo`` argument, it does from the root of repository with ``/NEMO``, ``/utils``, ``/vendors``. |
---|
| 173 | |
---|
| 174 | Create 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 | |
---|
| 211 | Download 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 | |
---|
| 222 | Delete 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 | |
---|
| 235 | Working smart with available resources |
---|
| 236 | ====================================== |
---|
| 237 | |
---|
| 238 | Make link between commit and ticket(s) |
---|
| 239 | -------------------------------------- |
---|
| 240 | |
---|
| 241 | If 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 | |
---|
[10655] | 246 | | To do so, |
---|
| 247 | you can use a word from this list ``addresses re references refs see`` followed by usual ticket link(s). |
---|
[10649] | 248 | | For instance |
---|
| 249 | |
---|
| 250 | .. code:: console |
---|
| 251 | |
---|
| 252 | $ svn commit -m '[...] see #${TICKET_ID} [...]' |
---|
| 253 | |
---|
| 254 | Close ticket(s) when committing |
---|
| 255 | ------------------------------- |
---|
| 256 | |
---|
[10655] | 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). |
---|
[10649] | 261 | | For instance |
---|
| 262 | |
---|
| 263 | .. code:: console |
---|
| 264 | |
---|
| 265 | $ svn commit -m '[...] fix #${TICKET_ID} [...]' |
---|