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 47 (modified by nicolasmartin, 6 years ago) (diff)

--

Developing code change

Last edition: Wikinfo(changed_ts)? by Wikinfo(changed_by)?

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 efficient 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.

Development Procedure

Description

A brief overview of the process is given below.

Error: Failed to load processor graphviz
No macro or processor named 'graphviz' found

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, and a previewer (which will also be the reviewer).
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.

Action Workflow

Follow-up & Development plan

Each action must have a wikipage and a ticket related to it. Browse to the current workplan page wiki/${YEAR}WP to create them and find the content and status of all planned actions in the workplan.

In addition to the general informations of the action (subject, people involved, resources, ...), the wikipage will describe in details:

  • Implementation plan: scientific context with references, code modifications with modules/files/variables and documentation changes (reference manual, wiki, ...)
  • Validation results from list of tests to ensure the development produces the anticipated effects and doesn't not impact unexpectedly the operation of the code and its other components, see below
  • (Pre,Re)view finding: decision with comprehensive feedbacks

Please follow carefully the indications in 'Help' section to avoid issues when editing the wikipage and the form fields.

The ticket will monitor the progress in the development and so it should be updated as the work goes on. In that regard, the commits with a clear reference to the ticket in the log message (#XXXX) will be listed in the 'Commit History' Section.

Once the 1st part of the wikipage 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 from submission date).
The PI is responsible to give all requested details. The Previewer is responsible to check with all experts that implementation plan is indeed correct 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).

Coding & Validation

Start the coding

Once the Previewer has sent the green light (approval of development plan), the PI can created the corresponding development branch. This branch should be created from the up to date version of NEMO as chosen for each year (usually the trunk at a given revision, see minutes of NEMO System Team videoconferences or our local NEMO representative).

Development branches will be created on the SVN repository under the directory svn/nemo/branches/$YEAR. The pattern for the branch name is: dev_${forking revision number}_${workplan item}-${keyword(s)} (ex 'dev_r8329_ENHANCE14_SAL')

Develop and document your change

Development can progress on this new branch. A few things to bear in mind when developing your changes:

  • Follow the appropriate coding standard, see NEMO coding standards document. Code should be documented on line as defined in the coding rules.
  • Ensure commit messages to your branch are meaningful, they are visible to everyone using the system.
  • Commit regularly and don't wait to have a certain amount of changes to do so, the debugging process will be easier with multiple small modifications by testing each revision one by one.
  • Changes in the reference manual should be also written as soon as possible, and before review process.

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 successful 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 successful specific tests: to be defined before starting, in order to check that development does indeed what is expected

Review

Once your development is completed, PI requests work of Reviewer(s) for scientific or technical correctness.

The reviewer should check that th development did indeed meet what has been approved at Preview step

  • The code changes are understood and appropriately made.
  • The documentation is sufficient to understand the code change and its impacts.

The Reviewers completes the review part of wiki page with the PI. Once all light are green, the development is approved and can be merged for the new release of NEMO (merging back with the trunk is not described here).