[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 | |
---|
| 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 | |
---|
| 19 | The *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 | |
---|
| 37 | Thanks to this, the *complementary code* can be shared between several branches. |
---|
| 38 | |
---|
| 39 | External sources in working copy |
---|
| 40 | -------------------------------- |
---|
| 41 | |
---|
| 42 | Here 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 | |
---|
| 62 | Developer 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 | |
---|
| 80 | The 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 | |
---|
| 95 | Recommended development environment |
---|
| 96 | =================================== |
---|
| 97 | |
---|
| 98 | Lightweight 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 | |
---|
| 104 | Although 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 |
---|
| 106 | set up a clean and minimal environment**. |
---|
| 107 | From there, the developer would be able to start his developments but |
---|
| 108 | also 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 | |
---|
| 117 | The 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 | |
---|
| 128 | Examples |
---|
| 129 | -------- |
---|
| 130 | |
---|
| 131 | Usage of ``install_dev_env.sh`` |
---|
| 132 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
| 133 | .. code:: console |
---|
| 134 | |
---|
| 135 | $ ./install_dev_env.sh [${DEVELOPER_ID} [repo]] |
---|
| 136 | |
---|
| 137 | Positional arguments in option |
---|
| 138 | |
---|
| 139 | 1. ``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). |
---|
| 142 | 2. ``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 | |
---|
| 146 | Create 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 | |
---|
| 183 | Download 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 | |
---|
| 194 | Delete 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 | |
---|
| 207 | Working smart with available resources |
---|
| 208 | ====================================== |
---|
| 209 | |
---|
| 210 | Make link between commit and ticket(s) |
---|
| 211 | -------------------------------------- |
---|
| 212 | |
---|
| 213 | If 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 | |
---|
| 225 | Close 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} [...]' |
---|