New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 10655 – NEMO

Changeset 10655


Ignore:
Timestamp:
2019-02-08T21:17:34+01:00 (6 years ago)
Author:
nicolasmartin
Message:

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

Location:
utils/dev
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • utils/dev/README.rst

    r10649 r10655  
    1212------------------------------- 
    1313 
    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). 
     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). 
    1617| For more, read `the documentation on external definitions in ​the SVN book 
    1718  <http://svnbook.red-bean.com/en/1.7/svn.advanced.externals.html>`_. 
    1819 
    19 The *core code*, which is actively developed from one release to another, is still present and unique for a branch. 
     20On one hand, the *core code*, which is actively developed from one release to another, 
     21is still present and unique for a branch. 
    2022 
    2123:./cfgs:  Reference configurations 
    … …  
    2426:./tests: Test cases 
    2527 
    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. 
     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. 
    2934 
    3035:./arch:     Settings for computing architecture 
    … …  
    3540:./tools:    User tools 
    3641 
    37 Thanks to this, the *complementary code* can be shared between several branches. 
     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. 
    3847 
    3948External sources in working copy 
    … …  
    5665.. important:: 
    5766 
    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. 
     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. 
    6179 
    6280Developer perspective 
    6381--------------------- 
    6482 
    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 
     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. 
    81104 
    82105.. code:: sh 
    … …  
    90113.. warning:: 
    91114 
    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. 
     115    Think about committing your new definitions 
    94116 
    95117Recommended development environment 
    … …  
    110132| Actually the script will checkout the repository in a slightly different manner from the usual way, 
    111133  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``). 
     134  download the sub-paths of the default development organisation in various depths 
     135  (``branches``, ``releases``, ``tags`` and ``trunk``). 
    113136| In the end, the developer will have a versioned copy of the repository first levels with empty folders, 
    114137  except for the `trunk` (``/NEMO/trunk``) and the last official release (``/NEMO/releases/release-X.X``) 
    115138  which have been fully downloaded. 
    116139 
    117 The benefits of this new approach are numerous: 
     140The benefits of this new approach are numerous 
    118141 
    119142- **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. 
     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. 
    122147- **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://...``). 
     148  no more tedious URL scheme to use (``svn+ssh://...``). 
    124149- **All developments handled in one common location** by 
    125150  putting an end at the branches scattering with several isolated working copies 
    … …  
    1391641. ``DEVELOPER_ID``: configure the working copy in developer mode, 
    140165   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``. 
     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``. 
    144172   With ``repo`` argument, it does from the root of repository with ``/NEMO``, ``/utils``, ``/vendors``. 
    145173 
    … …  
    216244  - URL link(s) to selected ticket(s) will be provided in the email notification and the changeset page. 
    217245 
    218 | To do so, you can use a word from this list ``addresses re references refs see`` followed by usual ticket link(s). 
     246| To do so, 
     247  you can use a word from this list ``addresses re references refs see`` followed by usual ticket link(s). 
    219248| For instance 
    220249 
    … …  
    226255------------------------------- 
    227256 
    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). 
     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). 
    230261| For instance 
    231262 

  • utils/dev/install_dev_env.sh

    r10637 r10655  
    99 
    1010dir='NEMO_dev' 
    11 if [ "$2" == 'repo' ]; then root=''; else root='NEMO'; fi 
     11 
     12if [ "$2" == 'repo' ]; then root='/'; else root='/NEMO'; fi 
    1213 
    1314## Copy of the repository with empty root directories 
    14 svn co --depth immediates http://forge.ipsl.jussieu.fr/nemo/svn/$root $dir 
     15echo 'Checkout the repository from' $root 
     16svn co --depth empty http://forge.ipsl.jussieu.fr/nemo/svn/$root $dir 
     17echo 
    1518 
    1619## Switch to developer role if ID is provided 
    1720if [ -n "$1" ]; then 
     21    echo 'Switch from user to developer role (http:// => svn+ssh://)' 
    1822    ssh-copy-id -i ~/.ssh/id_rsa.pub $1@forge.ipsl.jussieu.fr 2> /dev/null 
    19     svn sw --relocate http://forge.ipsl.jussieu.fr            \ 
    20    svn+ssh://$1@forge.ipsl.jussieu.fr/ipsl/forge/projets \ 
     23    svn sw --relocate    http://forge.ipsl.jussieu.fr                       \ 
     24                 svn+ssh://$1@forge.ipsl.jussieu.fr/ipsl/forge/projets \ 
    2125   NEMO_dev 
     26    echo 
    2227fi 
    2328 
    2429if [ "$2" == 'repo' ]; then 
    25     svn up --set-depth immediates $dir/utils $dir/vendors 
     30    echo "With 'repo' arg, create a lightweight copy of the repository" 
     31    echo "for the developement of the sources used as 'externals'" 
     32 
     33    for item in utils/build/{arch,makenemo,mk} utils/tools       \ 
     34      vendors/{AGRIF/dev,AGRIF/release-4.0,FCM,IOIPSL}  ; do 
     35#     vendors/{AGRIF/dev,AGRIF/stable,FCM,IOIPSL}  ; do 
     36   echo '¤' $item 
     37   svn up -q --parents $dir/$item 
     38    done 
     39    
    2640    dir=$dir/'NEMO' 
     41    echo 
    2742fi 
    2843 
    2944## Get the 1st level tree under 'branches' and 'releases' 
    30 svn up --set-depth immediates $dir/branches $dir/releases 
     45echo "Get empty development folders under '/NEMO/branches':" {UKMO,2018,2019} 
     46svn up -q --set-depth empty --parents $dir/branches/{UKMO,2018,2019} 
     47echo 
    3148 
    3249## Download trunk and last release 
    33 svn up --set-depth infinity $dir/trunk 
    34 svn up --set-depth infinity $dir/releases/release-3.6 
     50echo 'Full download of 2 main branches' 
     51echo "¤ '/NEMO/trunk'" 
     52svn up -q           $dir/trunk 
     53 
     54echo "¤ latest in '/NEMO/releases'" 
     55svn up -q --parents $dir/releases/release-4.0 
    3556 
    3657exit 0 
Note: See TracChangeset for help on using the changeset viewer.