= Developing code change [[PageOutline(2-3)]] 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. {{{#!div class="" style="text-align: center" {{{#!graphviz digraph { label = "Yearly Development Process"; rankdir = LR; labelloc = t; labeljust = left Workplan [ shape = egg, label = "Workplan", style = filled ] subgraph clusterWorkflow { label = "Worflow per action"; peripheries = 0; labeljust = centered;/* labelloc = b */ Actions [ shape = record, label = " Action A | Action B\n(cancelled) | Action C | Action D | Action E" ] Workflow [ shape = Mrecord, label = "{ Development Plan | Preview | Coding\n&\nValidation | Review }" ] Branches [ shape = record, label = "Branch A\n(validated) | Branch C\n(declined) | Branch D\n(validated) | Branch E\n(incomplete)" ] } Workplan -> Actions:aA; Workplan -> Actions:aB Workplan -> Actions:aC; Workplan -> Actions:aD Workplan -> Actions:aE Actions:aA -> Workflow:w [ style = dotted ]; Actions:aB -> Workflow:w [ style = invis ] Actions:aC -> Workflow:w [ style = dotted ]; Actions:aD -> Workflow:w [ style = dotted ] Actions:aE -> Workflow:w [ style = dotted ] Workflow:e -> Branches:bA [ style = dotted, color = green4 ]; Workflow:e -> Branches:bC [ style = dotted, color = red3, arrowhead = box ] Workflow:e -> Branches:bD [ style = dotted, color = green4 ]; Workflow:e -> Branches:bE [ style = dotted, color = orange2 ] Branches:bA -> Merge:w [ style = bold, color = green4 ]; Branches:bC -> Merge [ style = invis ] Branches:bD -> Merge:w [ style = bold, color = green4 ] Branches:bE:e -> Workplan:sw [ color = orange2, arrowhead = inv ] Merge [ shape = box, label = "Integration at\n\"NEMO Merge Party\"", style = "rounded, filled", margin = 0,0, color = lightblue1 ] } }}} }}} === 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. === Implementation plan and preview The PI should first describe the foreseen development and implementation plan in the 1^st^ part of the wikipage (detailed implementation plan). The PI will then 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 Changes Test your change appropriately and record the results in the wiki page for your action. 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 The SETTE script allow to check in sequence that nothing has been broken for the reference configurations. This script and the associated information needs to be downloaded: {{{ cd "my working directory" svn co https://forge.ipsl.jussieu.fr/nemo/svn/utils cd utils/CI/sette }}} * Once you have sucessfuly ran the sette.sh script, the sette_rpt.sh scripts summarizes the results of your test. If you get some changes in results or some errors , those have to be justified and reported in detail in the wiki page for the reviewer. 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 during preview phase, including use of associated test case 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).