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 1 (modified by rblod, 14 years ago) (diff)

--

Developing code change

Last edited Timestamp?


A brief overview of the process is given below:

  1. ''Plan your change'''
  2. '''Create a Ticket'''. This is used to document the change and review status.
  3. '''Create a Branch'''. This is a copy of the code which you will use to develop a change.
  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.

Plan Your Change

Discussions at an early stage with the NEMO Systems team/code owners should help make sure your change is viable, desirable and as easy as possible.

Create a Ticket

When a code change is being planned a ticket should be created describing the purpose of the change. 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 ''value'' 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 at this stage.

Create a Branch

A development (dev) branch should be created and development can progress on this branch in the normal manner.

Branches may be created from any point on the trunk, but will tend to be from either a stable release, or the head. When creating branches from a release, use the appropriate revision keyword for that release.

When you create branches, please use a standard name : DEV_starting revision number_purpose (ex DEV_r1302_obc)

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

  • Testing on a variety of processor configurations (1xM, Nx1 and MxN are recommended)
  • Global and Limited-Area Models
  • Coupled Models?
  • If adding new functionality, remember to test that your new code doesn't change results when it is switched off.

Document your Change

  • Any change will need documenting. If the documentation is fairly short (i.e. a small change with strictly limited impact), then the ticket will be an appropriate place for this. If documentation is more extensive, then a Trac wiki page should be used.
  • The convention for naming wiki pages associated with tickets is to replace "ticket/xxxx" with "wiki/ticket/xxxx" for ticket number "xxx".
  • The wiki page can be created by including the markup wiki:ticket/xxxx (where xxxx is your ticket number) in your ticket and then following the link.
  • A sample wiki template (NEMOTicketTemplate) is provided when creating the wikipage

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