.. _daily-work:

Daily work
==========

Create an issue in GitLab
-------------------------

If the work you're planning to do in your branch does not address an
existing issue, consider creating one in the main `project page
<https://git.smhi.se/ec-earth/ecearth4>`_. This gives you an
opportunity to describe what you're planning to do and it creates a
space to discuss and document any progress and to get feedback.

.. _create-dev-branch:

Create branches
---------------

New lines of development are carried out in dedicated branches. In
most cases you will branch off the stable ``main`` branch from the
``upstream`` remote. Decide on a meaningful name (here called
MYBRANCH) and create branches in the superproject and in the component
your are about to modify.

First in the EC-Earth superproject:
  
.. code-block:: bash

   cd ecearth4
   git checkout -b MYBRANCH upstream/main
   git submodule update --recursive

Then in the submodule. Continuing with the OpenIFS example:

.. code-block:: bash

   cd ecearth4/sources/oifs-43r3v2
   git checkout -b MYBRANCH upstream/main


Development
-----------

Once your branches are setup, you can start editing the source code to
implement your feature or bug fixes. Test and debug as needed. You
will likely record intermediate steps in you repositories, which is
detailed in the next section.

Stage and commit your changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Always start **FIRST** with the submodules if they have been modified:

.. code-block:: bash

   cd ecearth4/sources/oifs-43r3v2
   git add FILENAMES-TO-COMMIT
   git commit -m "A nice but not too long (max 60) commit message"

This can be repeated as often as needed. If you want to add more
information to the commit message, you can use a file with ``-F file``
instead of ``-m message``, where you leave a blank line between the
title (1st line) and the rest of your message.
     
Once you are done committing in your component, you can move
to the |ece4| project and check its status:

.. code-block:: bash

   cd ecearth4
   git status

will show that the submodule has been modified (the branch name is
sandbox in this example):
     
.. code-block:: bash
   :emphasize-lines: 7

   [2037] (sandbox *) >>> git status
   On branch sandbox
   Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git restore <file>..." to discard changes in working directory)
   
              modified:   sources/oifs-43r3v2 (new commits)
      
Stage and commit the submodule change detected by the main project:

.. code-block:: bash

   git add sources/oifs-43r3v2/
   git commit -m "Record very interesting recent commits in oifs"
        
Other regular changes outside the submodules are dealt with as usual.
For example, a new file:

.. code-block:: bash

   [2041] (sandbox %) >>> git status
   On branch sandbox
   Untracked files:
     (use "git add <file>..." to include in what will be committed)
     
           runtime/classic/THIS-DIR-IS-NOT-USED-ANYMORE

can be added to the local repository with:
     
.. code-block:: bash

   git add runtime/classic/THIS-DIR-IS-NOT-USED-ANYMORE
   git commit -m "Add a warning file"


Share through GitLab
~~~~~~~~~~~~~~~~~~~~

Once in a while, you should update your remote repositories. As always,
*start with the modified submodules* if any:

.. code-block:: bash

   cd ecearth4/sources/oifs-43r3v2
   git push origin HEAD
     
then move on to the superproject:
     
.. code-block:: bash

   cd ecearth4
   git push origin HEAD


Create Merge Requests
---------------------

Once your branches are matured and ready to be merged into the main
project, you will create merge requests (MR). Again, start with the
modified components if any:

* Visit your component project page ``https://git.smhi.se/YOURNAMESPACE/oifs43r3``
* Click on "Merge requests" on the left panel
* Then on the "New merge request" in the middle of the page
* You'll see a page like this:

  .. figure:: fig_mr-oifs43r3-init.png
     :alt: MR screenshot

  For the source, choose your branch. For the target, the original
  project you forked should be proposed and the branch should be
  ``main``. The last commit of both source and target is shown:

  .. figure:: fig_mr-oifs43r3.png
     :alt: MR screenshot

* Click on "Compare branches and continue". Add a title, description,
  **assignee**, etc... and when ready click on "Create merge request".
  Note the MR number. It starts with an exclamation mark (eg: !23).
  
* Repeat the procedure and create a MR in your EC-Earth superproject
  web page: ``https://git.smhi.se/YOURNAMESPACE/ecearth4``. If you
  have created a MR in one of the submodule, you can refer to it in
  your MR description and/or title. For example with::
  
    This (EC-Earth) MR extends functionality Y. For this, it makes use of 
    the new feature X in OpenIFS, see ec-earth/vendor/openifs/oifs43r3!23


Cleaning up
-----------

Removing old branch
~~~~~~~~~~~~~~~~~~~

Once the MRs have been merged, you should remove the branch and start
afresh. Starting with the modified component:

.. code-block:: bash

   cd ecearth4/sources/oifs-43r3v2
   git checkout main  #any branch is fine, as long as it is not MYBRANCH
   git branch -d MYBRANCH

You should also remove the branch in GitLab, either through the web
interface or by entering:

.. code-block:: bash

   git push origin --delete MYBRANCH

Then repeat the same calls in the |ece4| project:

.. code-block:: bash

   cd ecearth4
   git checkout main      #any branch is fine, as long as it is not MYBRANCH
   git submodule update --recursive
   git branch -d MYBRANCH

You should also remove the branch in GitLab, either through the web
interface or by entering:

.. code-block:: bash

   git push origin --delete MYBRANCH

Updating your main branches
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before starting some new development, it is also recommended to get
the latest update from upstream:

.. code-block:: bash

   cd ecearth4
   git fetch --all    #or: 'git remote update' if you prefer
   git checkout main
   git merge --ff-only upstream/main
   git push origin HEAD
   git submodule update --init --recursive

You should be ready to create new branches starting from the latest
stable point of the ecearth4 project.

If you want to also update your submodule fork, follow these steps (continuing with our OpenIFS
example):

.. code-block:: bash

   cd ecearth4/sources/oifs-43r3v2
   git fetch --all    #or: 'git remote update' if you prefer
   git checkout main
   git merge --ff-only upstream/main
   git push origin HEAD

Note that if you are not planning to modify the submodule anymore you
should set it back to the commit recorded in ecearth4:

.. code-block:: bash

   cd ecearth4
   git submodule update --recursive


Advance settings
----------------

You may have noticed that you always push your local branch to a
branch with the same name in your fork (origin):

.. code-block:: bash

   git push origin HEAD

If you set:

.. code-block:: bash

   cd ecearth4
   git config remote.pushdefault origin
   # and
   cd ecearth4/sources/oifs-43r3v2
   git config remote.pushdefault origin

you can just type:

.. code-block:: bash

   git push

This setting affects only branches with an upstream branch in the
upstream remote (see :ref:`create-dev-branch`). If you create a branch
with:

.. code-block:: bash

   cd ecearth4
   git checkout -b MYBRANCH origin/somebranch

a simple call to ``git push`` will complain. To make it work, you need
to set:

.. code-block:: bash

   cd ecearth4
   git config push.default current