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.
Developers/DevelopingCodeChanges – NEMO
wiki:Developers/DevelopingCodeChanges

Version 15 (modified by clevy, 8 years ago) (diff)

--

Developing code change

Last edited Timestamp?


History

Until end of 2015, the PI if a given development action was expected to develop the code and its documentation in a development branch, to go through the different validation steps, and to submit it at the end to a reviewer, the positive answer of the review being a prerequisite for a merge into the NEMO reference.
Since Merge Party meeting end of 2015, the process has been changed to a more efficent and reliable process, in order to avoid disagreement and a lock at the review step. The sequence described below is presently to be followed for each development of the NEMO System Team's workplan.

A brief overview of the process is given below:

  1. Workplan content: Each development action is expected to be described in the yearly workplan
  2. Detailed description of tasks and Preview step
  3. Start the coding. The branch is a copy of the up to date reference that will be used to develop the changes.
  4. '''Develop your Change'''. Checkout your branch base code, develop and commit changes to your branch.
  5. '''Test your Change'''. Make sure you test your changes adequately.
  6. '''Document your Change'''. Update your ticket with all the information that another user/developer might need.
  7. '''Science/Tech/Code? Review'''. Review of the change by an expert on the scientific or technical area you are changing and for adherence to coding standards.

Merging back with the trunk is not described here.

Workplan content

The yearly workplan is discussed within System Team, submitted to Developer's Committee, and approved by Steering Committee. It must include, for each development action, its motivation, status, main tasks so as a PI name, and a previewer (which will also be the reviewer) name. If needed, previewer can be divided into a "Science Previewer" and a "System Previewer". The name of Previewer should be added only once he did accept the task, and before submission of workplan to Developer's Committee.

Detailed description of tasks and Preview step

Once the workplan has been approved, the code development is planned. The PI should

  • create a ticket to start the work. This ticket will describe the purpose of the action, so as Pi and Previewer name.
  • Create an associated wiki page using the template XXX (to be created). This wiki page will permit to follow the ongoing work through different steps. The wiki page will be linked to the ticket.

The other fields in the ticket (e.g. Priority, Milestone, Keywords etc) should also be set appropriately.

  • The ''milestone'' field should be set to the area the change is being targeted for.
  • The ticket ''type'' field should be set to "development branch"
  • Associated wiki page should be created by including the markup wiki:ticket/xxxx (where xxxx is your ticket number) in your ticket and then following the link.
  • The ticket should be assigned to the code developer and the previewer at this stage.

The wiki page will describe:

  • Purpose and associated action number on workplan
  • Motivation
  • Status
  • Main tasks
  • Pi name
  • Previewer(s) name
  • Detailed implementation plan (scientific and technical): list of files and routine names of the code to be changed or created, new variable names (following coding rules)... This is also expected to be used as summary of changes to NEMO reference manual to be written later
  • Detailed list of specific tests, see below

Once the wiki page is completed by PI (detailed implementation plan), the PI will submit it to Previewer. The Previewer will discuss with PI to reach full agreement on detailed implementation plan (in a maximum of 2 weeks starting when PI submits wiki page to Previewer).
The PI is responsible to give all requested details.
The Previewer is responsible to check with all experts that implementation plan is indeed coorect and compatible with the other developments going on in parallel during the year. Objective is to avoid the need for a full rewriting at the end (which did happen sometimes previously)

Start the coding

Once the Previewer has sent the green light (approval of detailed implementation plan and summary of changes in reference manual), the PI can created the corresponding development branch. The branch should be created from the up to date version of NEMO as chosen for each year (usually the trunk at a give fixed revision for a give year, see minutes of NEMO System Team videoconferences. Development can progress on this new branch.

Each year, development branches will be created in the directory svn/nemo/branches/YEAR/"standard name of dev branch".
"standard name of dev branch" should be: dev_"starting revision number"_"workplan item_purpose" (ex dev_r1302_LOCEAN1_mpp)

Develop your Change

A few things to bear in mind when developing your changes,

  • Follow the appropriate coding standard, see NEMO coding standards document.
  • Ensure commit messages to your branch are meaningful. They are visible to everyone using the system.
  • You don't have to commit to your branch to test a change. You can compile from a working copy.

Test your Change

Test your change appropriately and record the results. The testing required will depend on the change and the potential impact on other configurations. When testing, things to consider include

  • full sucessfull SETTE tests: to check nothing is broken or goes wrong in the reference configurations SETTE tests: if running with some changes in the results, those have to be justified and checked in detail. New code should not change results when it is switched off, and not alter results when tuned on.
  • full succesfull specific tests: to be defined before starting, in order to check that development does indeed what is expected
  • Add here possible use of Trusting tool for a development branch (Nicolas?)

Document your Change

  • Progress in the development should be documented as the work goes on in the ticket created at the beginning/
  • Code should be documented on line as defined in the coding rules
  • Changes in the reference manual should be also written as soon as possible, and before review process

Science/Tech/Code? Review

Once your change is complete, you will need to get it reviewed for scientific or technical correctness.

To assign your ticket for its first review,

  • ask for a reviewer during the video conference

The reviewer should check that

  • The code changes are understood and appropriately made.
  • The documentation is sufficient to understand the code change and its impacts.
  • Complete a wiki review template (https://forge.ipsl.jussieu.fr/nemo/wiki/PageTemplates/NEMOTicketTemplate) and append it to the ticket.
  • Use the wiki filename convention wiki:ticket/xxxx/Review where xxxx is the ticket number.It is likely that the review process will involve iterations between code author and reviewer until documentation and change are agreed to be of sufficient quality. The reviewer has the option to "reject & assign" back to the code author should the documentation/code not meet the required standards and major alterations/improvements are required.

Once the reviewer is satisfied, he/she should complete the approval section of the review template.

Video tutorial

see the Working Practices, the movie