-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathfims_workflow.tex
1754 lines (1415 loc) · 89.1 KB
/
fims_workflow.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% Options for packages loaded elsewhere
\PassOptionsToPackage{unicode}{hyperref}
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[
]{book}
\title{FIMS Developer Handbook}
\author{FIMS implementation team}
\date{2022-02-17}
\usepackage{amsmath,amssymb}
\usepackage{lmodern}
\usepackage{iftex}
\ifPDFTeX
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{textcomp} % provide euro and other symbols
\else % if luatex or xetex
\usepackage{unicode-math}
\defaultfontfeatures{Scale=MatchLowercase}
\defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
\fi
% Use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
\IfFileExists{microtype.sty}{% use microtype if available
\usepackage[]{microtype}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\makeatletter
\@ifundefined{KOMAClassName}{% if non-KOMA class
\IfFileExists{parskip.sty}{%
\usepackage{parskip}
}{% else
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}}
}{% if KOMA class
\KOMAoptions{parskip=half}}
\makeatother
\usepackage{xcolor}
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
\hypersetup{
pdftitle={FIMS Developer Handbook},
pdfauthor={FIMS implementation team},
hidelinks,
pdfcreator={LaTeX via pandoc}}
\urlstyle{same} % disable monospaced font for URLs
\usepackage{color}
\usepackage{fancyvrb}
\newcommand{\VerbBar}{|}
\newcommand{\VERB}{\Verb[commandchars=\\\{\}]}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}
% Add ',fontsize=\small' for more characters per line
\usepackage{framed}
\definecolor{shadecolor}{RGB}{248,248,248}
\newenvironment{Shaded}{\begin{snugshade}}{\end{snugshade}}
\newcommand{\AlertTok}[1]{\textcolor[rgb]{0.94,0.16,0.16}{#1}}
\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.77,0.63,0.00}{#1}}
\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\BuiltInTok}[1]{#1}
\newcommand{\CharTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\ErrorTok}[1]{\textcolor[rgb]{0.64,0.00,0.00}{\textbf{#1}}}
\newcommand{\ExtensionTok}[1]{#1}
\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\ImportTok}[1]{#1}
\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
\newcommand{\NormalTok}[1]{#1}
\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
\newcommand{\RegionMarkerTok}[1]{#1}
\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\StringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\usepackage{longtable,booktabs,array}
\usepackage{calc} % for calculating minipage widths
% Correct order of tables after \paragraph or \subparagraph
\usepackage{etoolbox}
\makeatletter
\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{}
\makeatother
% Allow footnotes in longtable head/foot
\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}}
\makesavenoteenv{longtable}
\usepackage{graphicx}
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi}
\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi}
\makeatother
% Scale images if necessary, so that they will not overflow the page
% margins by default, and it is still possible to overwrite the defaults
% using explicit options in \includegraphics[width, height, ...]{}
\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}
% Set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother
\setlength{\emergencystretch}{3em} % prevent overfull lines
\providecommand{\tightlist}{%
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setcounter{secnumdepth}{5}
\usepackage{booktabs}
\ifLuaTeX
\usepackage{selnolig} % disable illegal ligatures
\fi
\usepackage[]{natbib}
\bibliographystyle{plainnat}
\begin{document}
\maketitle
{
\setcounter{tocdepth}{1}
\tableofcontents
}
\hypertarget{about}{%
\chapter{About}\label{about}}
This is a book written in \textbf{Markdown} describing the FIMS development workflow. This section describes how to edit and contribute to the book.
\hypertarget{usage}{%
\section{Usage}\label{usage}}
Each \textbf{bookdown} chapter is an .Rmd file, and each .Rmd file can contain one (and only one) chapter. A chapter \emph{must} start with a first-level heading: \texttt{\#\ A\ good\ chapter}, and can contain one (and only one) first-level heading.
Use second-level and higher headings within chapters like: \texttt{\#\#\ A\ short\ section} or \texttt{\#\#\#\ An\ even\ shorter\ section}.
The \texttt{index.Rmd} file is required, and is also your first book chapter. It will be the homepage when you render the book.
\hypertarget{render-book}{%
\section{Render book}\label{render-book}}
You can render the HTML version of this example book without changing anything:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
Find the \textbf{Build} pane in the RStudio IDE, and
\item
Click on \textbf{Build Book}, then select your output format, or select ``All formats'' if you'd like to use multiple formats from the same book source files.
\end{enumerate}
Or build the book from the R console:
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{bookdown}\SpecialCharTok{::}\FunctionTok{render\_book}\NormalTok{()}
\end{Highlighting}
\end{Shaded}
To render this example to PDF as a \texttt{bookdown::pdf\_book}, you'll need to install XeLaTeX. You are recommended to install TinyTeX (which includes XeLaTeX): \url{https://yihui.org/tinytex/}.
\hypertarget{preview-book}{%
\section{Preview book}\label{preview-book}}
As you work, you may start a local server to live preview this HTML book. This preview will update as you edit the book when you save individual .Rmd files. You can start the server in a work session by using the RStudio add-in ``Preview book'', or from the R console:
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{bookdown}\SpecialCharTok{::}\FunctionTok{serve\_book}\NormalTok{()}
\end{Highlighting}
\end{Shaded}
\hypertarget{code-of-conduct}{%
\chapter{Code of Conduct}\label{code-of-conduct}}
\hypertarget{fims-contributor-conduct}{%
\section{FIMS Contributor Conduct}\label{fims-contributor-conduct}}
All contributors participating and contributing to the FIMS project are expected to adhere to the \href{https://www.contributor-covenant.org/version/2/1/code_of_conduct/}{Contributor Covenant}. Briefly, these standards are adopted to ensure a positive and harassment-free enviroment for all participants. Examples of behavior that contributes to a positive environment for our community include:
\begin{itemize}
\tightlist
\item
Demonstrating empathy and kindness toward other people
\item
Being respectful of differing opinions, viewpoints, and experiences
\item
Giving and gracefully accepting constructive feedback
\item
Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
\item
Focusing on what is best not just for us as individuals, but for the overall community
\end{itemize}
\hypertarget{supporting-good-conduct}{%
\section{Supporting Good Conduct}\label{supporting-good-conduct}}
FIMS Community leaders will create default community health files (e.g.~CONTRIBUTING, CODE\_OF\_CONDUCT) to be used in all repositories owned by FIMS.
\hypertarget{reporting-unacceptable-behavior}{%
\subsection{Reporting Unacceptable Behavior}\label{reporting-unacceptable-behavior}}
Questions about the FIMS Code of Conduct or reports of unacceptable behavior should be sent to \href{mailto:[email protected]}{\nolinkurl{[email protected]}}. Reports will be reviewed by a member of the NOAA Fisheries Office of Science and Technology who is not participating in the FIMS Project {[}Jim Berkson{]}, but has the full support of FIMS Community Leaders. All reports will be reviewed promptly and fairly.
\hypertarget{consequences-of-violating-conduct}{%
\subsection{Consequences of Violating Conduct}\label{consequences-of-violating-conduct}}
People who violate the FIMS Contribute Conduct will face meaningful consequences, up to and including explusion from the FIMS Community. The Code of Conduct, as well as consequences for violations, apply equally to all participants.
\hypertarget{style-guide}{%
\chapter{Style Guide}\label{style-guide}}
The FIMS project uses style guides to ensure our code is consistent, easy to use (e.g.~read, share, and verify), and ultimately easier to write. We use the \href{https://google.github.io/styleguide/cppguide.html}{Google C++ Style Guide} and \href{https://google.github.io/styleguide/Rguide.html}{Google's R Style Guide}. Google's R Style Guide is based off of the \href{https://style.tidyverse.org/}{tidyverse style guide}, with a few minor modifications to improve readability and portability.
\hypertarget{fims-governance}{%
\chapter{FIMS Governance}\label{fims-governance}}
The \href{https://drive.google.com/file/d/1gMDQbAhjM2E3nct4Hc6u-DT1Ta8bizLd/view?usp=sharing}{FIMS Terms of Reference} describes the high level organization of the FIMS Project. Additional details on roles and responsibilities are provided here.
\hypertarget{developers}{%
\section{Developers}\label{developers}}
Developers are expected to adhere to the principles and guidelines outlined within this handbook, including the \protect\hyperlink{code-of-conduct}{Code of Conduct}, \protect\hyperlink{style-guide}{Style Guide}, \protect\hyperlink{issue-tracking}{Issue Tracking}, and \protect\hyperlink{test-case-template}{Test Case Template}. The developer responsibilities include:
\begin{itemize}
\tightlist
\item
Writing the module code.
\item
Creating documentation for the module and building the documentation to ensure it is error-free.
\item
Implementing the suite of required test cases for the module.
\item
Ensuring the module runs through the FIMS Github actions.
\end{itemize}
Once development of a bug fix or a new component of FIMS is complete, the developer should create a \protect\hyperlink{pull-requests}{pull request} according to the correct template and assign the issue tracking the completion of the bug fix and/or feature to the assigned review team. The developer must resolve any issues arising from the review and get confirmation from the review team before the pull request is merged into the upstream branch.
\hypertarget{reviewers}{%
\section{Reviewers}\label{reviewers}}
The reviewers are responsible for adhering to documented guidelines in the \protect\hyperlink{code-review}{Code Review} section. Reviewers should confirm that the new code is able to build and run within their own development environment. Reviewers should clearly document which components of the code need to be improved to be accurate, comply with project guidelines and style, or do not work, in the pull request thread so that the developer knows what they need to fix.
\hypertarget{project-lead}{%
\section{Project Lead}\label{project-lead}}
The Project Lead is responsible for ensuring development and code review occur in a timely manner and according to project guidelines and standards. The Project Lead will triage issues and pull requests weekly and prompt involved parties to resolve outstanding issues and reviews. The Project Lead is also responsible for communicating project status via maintenance of the \href{https://noaa-fims.github.io/status}{status dashboard}.
\hypertarget{director-of-software-development}{%
\section{Director Of Software Development}\label{director-of-software-development}}
The Director of Software Development is responsible for the successful creation and delivery of the FIMS product to the end user by managing technical risks and opportunities; making key~software design~and implementation decisions with the development teams, scheduling of tasks, managing~change requests, and guaranteeing quality of deliveries and educating the team on technical~best practices.
\hypertarget{code-of-conduct-adjudicator}{%
\section{Code of Conduct Adjudicator}\label{code-of-conduct-adjudicator}}
The Code of Conduct Adjudicator is responsible for responding to allegations of \protect\hyperlink{code-of-conduct}{Code of Conduct} violations in an appropriate manner. This could include a conversation with the violator, his or her manager, up to and including expulsion from the FIMS development team. If the violator is an external collaborator, they can be banned from contributing to the FIMS Github resources in the future.
\hypertarget{external-collaborators}{%
\section{External Collaborators}\label{external-collaborators}}
External collaborators interested in contributing to FIMS development are required to fork the FIMS repository, make changes, and submit a pull request. However, collaborators are strongly encouraged to submit an issue via the main FIMS repository for discussion prior to forking. In general, forks are discouraged for development that is intended for integration into FIMS as it becomes difficult to keep track of multiple forks. If collaborators wish to use FIMS as a starting-point for a brand new project that they do not intend to merge back into the main branch, they can start a fork. However, if they intend to create a pull request, they should use a branch.
Pull requests from forks will be reviewed the same as a pull request submitted from a branch. Users will need to conform to the same standards and all contributions must pass the standard tests as well as provide tests that check the new feature.
\hypertarget{contributor-guidelines}{%
\chapter{Contributor Guidelines}\label{contributor-guidelines}}
External contributions and feedback are important to the development and future maintenance of FIMS and are welcome. This section provides information for FIMS developers and collaborators on how to contribute to the project.
\hypertarget{fims-branching-strategy}{%
\section{FIMS Branching Strategy}\label{fims-branching-strategy}}
There are several \href{https://reviewpad.com/blog/github-flow-trunk-based-development-and-code-reviews/}{branching strategies} available that will work within the Git environment and other version control systems. However, it is important to find a strategy that works well for both current and future contributors. Branching strategies provide guidance for how, when, and why branches are created and named, which also ties into necessary guidance surrounding issue tracking.
The FIMS Project uses a \href{https://trunkbaseddevelopment.com/}{Scaled Trunk Based Development} branching strategy to make tasks easier without compromising quality.
\begin{figure}
\centering
\includegraphics{https://reviewpad.com/wp-content/uploads/2021/06/Scaled-Trunk-Based-Development.svg}
\caption{Scaled Trunk Based Development; image credit: \url{https://reviewpad.com/blog/github-flow-trunk-based-development-and-code-reviews/}}
\end{figure}
This strategy is required for continuous integration and facilitates knowledge of steps that must be taken prior to, during, and after making changes to the code, while still allowing anyone interested in the code to read it at any time. Additionally, trunk-based development captures the following needs without being overly complicated:
\begin{itemize}
\tightlist
\item
Short-lived branches to minimize stale code and merge conflicts
\item
Fast release times, especially for bug fixes
\item
Ability to release bug fixes without new features
\end{itemize}
\hypertarget{branching-good-practices}{%
\subsection{Branching Good Practices}\label{branching-good-practices}}
The following suggestions will help ensure optimal performance of the trunk-based branching strategy:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
Branches and commits should be kept small (e.g.~a couple commits, a few lines of code) to allow for rapid merges and deployments.
\item
Use \href{https://martinfowler.com/articles/feature-toggles.html}{feature flags} to wrap new changes in an inactive code path for later activation (rather than creating a separate repository feature branch).
\item
Delete branches after it is merged to the trunk; avoid repositories with a large number of ``active'' branches.
\item
Merge branches to the trunk frequently (e.g.~\textbf{at least} every few days; tag as a release commit) to avoid merge conflicts.
\item
Use caching layers where appropriate to optimize build and test execution times.
\end{enumerate}
\hypertarget{branch-protection}{%
\subsection{Branch Protection}\label{branch-protection}}
Branch protection allows for searching branch names with \texttt{grep} functionality to apply merging rules (i.e., protection). This will be helpful to protect the main/trunk branch such that pull requests cannot be merged in prior to passing various checks or by individuals without the authority to do so.
\hypertarget{coding-good-practices}{%
\section{Coding Good Practices}\label{coding-good-practices}}
Following good software development and coding practices simplifies collaboration, improves readability, and streamlines testing and review. The following are industry-accepted standards:
\begin{itemize}
\tightlist
\item
Adhere to the \href{https://noaa-fims.github.io/collaborative_workflow/style-guide.html}{FIMS Project style guide}
\item
Avoid rework - take the time to check for existing options (e.g.~in-house, open source, etc.) before writing code
\item
Keep code as simple as possible
\item
Use meaningful variable names that are easy to understand and clearly represent the data they store
\item
Use descriptive titles and consistent conventions for class and function names
\item
Use consistent names for temporary variables that have the same kind of role
\item
Add clear and concise coding comments
\item
Use consistent formatting and indentation to improve readability and organization
\item
Group code into separate blocks for individual tasks
\item
Avoid hard-coded values to ensure portability of code
\item
Follow the DRY principle - ``Don't Repeat Yourself'' (or your code)
\item
Avoid deep nesting
\item
Limit line length (wrap \textasciitilde72 characters)
\item
Capitalize SQL queries so they are readily distinguishable from table/column names
\item
Lint your code
\end{itemize}
\hypertarget{issue-tracking}{%
\chapter{Issue Tracking}\label{issue-tracking}}
Use of the GitHub issue tracker is key to keeping everyone informed and prioritizing key tasks. All future projects, ideas, concerns, development,
etc. must be documented in an issue before the code is altered. Issues should be filed and tagged prior to any code changes whether the change
pertains to a bug or the development of a feature. At a minimum, all issues will be labeled with a future version number. Bugs with immediate fixes will
be assigned to the current version number augmented for a hot fix and development will be based on code in the trunk. All other issues will be
assigned to a future version and development will be based on version branches. That is, changes to the code for version 3.3 cannot start until there is a branch
for version 3.3. This will minimize stale code and large merge conflicts.
\hypertarget{issue-labels}{%
\section{Issue Labels}\label{issue-labels}}
Utilize labels on issues:
\begin{itemize}
\tightlist
\item
To describe the kind of work to be done: bug, enhancement, task, discussion, question, suitable for beginners
\item
To indicate the state of the issue: urgent, current, next, eventually, won't fix, duplicate
\end{itemize}
\hypertarget{issue-templates}{%
\section{Issue Templates}\label{issue-templates}}
There are two issue templates currently available in the FIMS repository.
1. \href{https://github.com/NOAA-FIMS/FIMS/blob/main/.github/ISSUE_TEMPLATE/feature_request.md}{Feature requests}: this template should be used to request new features or changes to features, such that the described functionality differs from what is currently in the development plan.
2. \href{https://github.com/NOAA-FIMS/FIMS/blob/main/.github/ISSUE_TEMPLATE/bug_report.md}{Bug reports}: this should be used to file bugs, which describe when the existing functionality differs from what is described in the development plan.
\hypertarget{issue-lifecycle}{%
\section{Issue Lifecycle}\label{issue-lifecycle}}
FIMS development will adhere to a lifecycle for issues that makes it clear which issues can be resolved when.
\begin{itemize}
\tightlist
\item
Creation --- The event that marks the creation of an issue. An issue is not Active when it is Created. Issues that are opened are assigned to the FIMS Project Lead with the label: \texttt{needs-triage}. A issue is not considered Active until this label is removed.
\item
Activation --- When the \texttt{needs-triage} label is removed and the issue is assigned to a developer, the issue becomes Active. This event happens once in the lifecycle of an issue. Activation usually is not undone but it can be undone if an issue needs additional discussion; in this case, the \texttt{needs-triage} label is applied again. An issue is Active from the time it is Activated until reaches Resolution.
\item
Response --- This event only happens if the triage team deems an issue to a wont-fix or delayed. This requires communication with the party who opened the issue as to why this will not be addressed or will be moved to a later milestone.
\item
Resolution --- The event that marks the resolution of an issue. This event happens once in the lifetime of an issue. This event can be undone if an issue transitions from a resolved status to an unresolved status, in which case the system considers the issue as never had been resolved. A resolution involves a code check-in and pull request, at which point someone must review and approve the pull request before the issue can transition states.
\item
In Review - The issue is ``in review'' after a code solution has been proposed and is being considered via a pull request. If this is approved, the issue can move into the ``Closed'' state.
\item
Closure---The event that marks the closure of an Issue. This even happens once in the lifetime of an issue. The issue can enter the Closed state from either the ``In Review'' or ``Response'' state.
\end{itemize}
\begin{figure}
\includegraphics[width=0.75\linewidth]{New Flowchart} \caption{Flow chart that describes above process visually, e.g. how an issue moves from creation, to activation, to response or resolution, and is finally closed.}\label{fig:flowchart}
\end{figure}
\hypertarget{pull-requests}{%
\section{Pull Requests}\label{pull-requests}}
Pull requests are used to identify changes pushed to development branches. Open pull requests allow the FIMS Development Team to discuss and review the changes, as well as add follow-up commits before merging to the main branch. As noted above in the branching stratgegy section, branches, commits, and pull requests should be kept small to enable rapid review and reduce the chance of merge conflicts. Any pull requests for the FIMS Project must be fully tested and reviewed before being merged into the main branch.
Use the \href{https://github.com/NOAA-FIMS/FIMS/blob/main/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md}{pull request template} to create pull requests. Pull requests without this template attached will not be approved.
\hypertarget{code-review}{%
\section{Code Review}\label{code-review}}
Code review ensures health and continuous improvement of the FIMS codebase, while simultaneously helping FIMS developers become familiar with the codebase and ensure there is a diverse team of knolwedgable collaborators to support the continued development and maintenance of FIMS. CI/CD requires rapid review of all new/modified code, so processes must be in place to support this pace. FIMS code review will utilize tools available via \href{https://github.com/features/code-review}{GitHub}, which allows reviewers to analyze code changes, provide inline comments, and view change histories.
\hypertarget{assigning-reviewers}{%
\subsection{Assigning Reviewers}\label{assigning-reviewers}}
Reviewers for the FIMS Project may be assigned in two different ways:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
A specific member of the FIMS Development Team is requested to review a pull request, based on their specific expertise.
\item
Code review assignments are automatically assigned using the \href{https://docs.github.com/en/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team}{GitHub load balance routing algorithm}; this approach tries to ensure that each team member reviews an equal number of pull request in any 30 day period.
\end{enumerate}
Team members should keep their status in Github current (see \href{https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile\#setting-a-status}{``Setting a status''} for more information). Reviews will not be auto-assigned to ``Busy'' team members.
If a review has been assigned to you and you don't feel like you have the expertise to address it properly, please respond directly to the code owner immediately so a different reviewer can be found promptly.
\hypertarget{automated-testing}{%
\subsection{Automated Testing}\label{automated-testing}}
Automated testing provides an initial layer of quality assurance and lets reviewers know that the code meets certain standards. For more on FIMS testing, see \href{https://noaa-fims.github.io/collaborative_workflow/test-case-template.html}{Chapter 6}.
\hypertarget{review-checklist}{%
\subsection{Review Checklist}\label{review-checklist}}
While automated testing can assure the code structure and logic pass quality checks, human reviewers are required to evaluate things like functionality, readability, etc. Reviewers should evaluate the code critically and provide comment/feedback on the following items:
\textbf{Readability}
\begin{itemize}
\tightlist
\item
Is the code easy to understand?
\item
Are there any parts of the code that are confusing?
\item
Is the data flow easy to understand?
\item
Is there any code commented out?
\item
Does the code include any unclear names?
\item
Does the code include any errors, repeats, or incomplete sections?
\end{itemize}
\textbf{Functionality}
\begin{itemize}
\tightlist
\item
Does the code function as it is expected to?
\item
How will the change impact other parts of the system?
\item
Are there any unhandled edge cases?
\item
Are there other code improvements possible?
\end{itemize}
\textbf{Design}
\begin{itemize}
\tightlist
\item
Are files organized intuitively?
\item
Are components divided up in a sensible way?
\item
Does the review include too many changes? Would the code change better be broken into more focused parts?
\item
Will the change be easy to maintain?
\item
Does the code follow object-oriented design principles?
\item
Is the code in the proper location?
\end{itemize}
\textbf{Security}
\begin{itemize}
\tightlist
\item
Does using this code open the software to possible security violations or vulnerabilities?
\item
Is the correct encryption used?
\end{itemize}
\textbf{Performance}
\begin{itemize}
\tightlist
\item
Are there ways to improve on the code's performance?
\item
Is there any complex logic that could be simplified?
\item
Could any of the code be replaced with built-in functions?
\item
Will this change have any impacts on system performance?
\item
Is there any debugging code that could be removed?
\item
Are there any optimizations that could be removed and still maintain system performance?
\end{itemize}
\textbf{Documentation}
\begin{itemize}
\tightlist
\item
Are there comments available to explain the code?
\item
Is the README file complete and current? Does it adequately describe the project/changes?
\end{itemize}
\textbf{Testing}
\begin{itemize}
\tightlist
\item
Is the code testable?
\item
Is the automated testing adequate?
\item
Have dependencies been appropriately tested?
\item
Does automated testing cover the code exchange adequately?
\item
Could the test structure be improved?
\end{itemize}
\hypertarget{review-good-practices}{%
\subsection{Review Good Practices}\label{review-good-practices}}
Good reviews require good review habits. Try to follow these suggestions:
\begin{itemize}
\tightlist
\item
Review in short sessions (\textless{} 60 minutes) to maintain focus and attention to detail
\item
Don't try to review more than 400 lines of code in a single session
\item
Provide constructive and supportive feedback
\item
Ask open-ended questions and offer alternatives or possible workarounds
\item
Avoid strong/opinionated statements
\item
Applaud good solutions
\item
Don't say ``you''
\item
Be clear about which questions/comments are non-blocking or unimportant; likewise, be explicit when approving a change or requesting follow-up
\item
Aim to minimize the number of nitpicks (if there are a lot, suggest a team-level resolution)
\item
Use the \href{https://noaa-fims.github.io/collaborative_workflow/style-guide.html}{FIMS Style Guide} to settle any style arguments
\end{itemize}
\hypertarget{commit-messages}{%
\section{Commit Messages}\label{commit-messages}}
FIMS Project contributors should provide clear, descriptive commit messages to communicate to collaborators details about changes that have occurred and improve team efficiency. Good commit messages follow the following practices:
\begin{itemize}
\item
Include a short summary of the change for the subject/title (\textless50 characters)
\item
Include a blank line in between the `subject' and `body'
\item
Specify the type of commit:
\begin{verbatim}
* fix: bug fix
* feat: new feature
* test: testing
* docs: documentation
* chore: regular code maintenance (e.g. updating dependencies)
* refactor: refactoring codebase
* style: changes that do not affect the meaning of the code; instead address code styling/formmatting
* perf: performance improvements
* revert: reverts a previous commit
* build: changes that affect the build system
\end{verbatim}
\item
If the commit addresses an issue, indicate the issue\# in the title
\item
Provide a brief explanatory description of the change, addressing what and why was changed
\item
Wrap to \textasciitilde72 characters
\item
Write in the imperative (e.g.~``Fix bug'', not ``Fixed bug'')
\item
If necessary, separate paragraphs by blank lines
\item
Utilize \texttt{BREAKING\ CHANGE:\ \textless{}description\textgreater{}} to provide expanation or further context about the issue being addressed.
\item
If the commit closes an issue, include a footer to note that (i.e.~``Closes \#19'')
\end{itemize}
\hypertarget{software-user-guide}{%
\chapter{Software user guide}\label{software-user-guide}}
This section describes how to install and run the model.
\hypertarget{installing-the-package-from-github}{%
\section{Installing the package from Github}\label{installing-the-package-from-github}}
\hypertarget{windows-users}{%
\subsection{Windows users}\label{windows-users}}
Before you install the \texttt{FIMS} package, you will need to install the Rtools executable corresponding to your \texttt{R} version as well as the \texttt{TMB} package and its dependencies. \texttt{FIMS} has only been developed and tested on \texttt{R} version 4.+, and so in order to install the package you will need to ensure you are using \texttt{R} version 4.+ and an RStudio version that is at least 1.2.5042. Instructions on how to install \texttt{Rtools} are \href{https://cran.r-project.org/bin/windows/Rtools/rtools40.html}{here}. Instructions on how to install \texttt{TMB} are \href{https://github.com/kaskr/adcomp/wiki/Download}{here}. Please ensure you have tested your \texttt{TMB} setup before moving on to install FIMS.
\hypertarget{mac-users}{%
\subsection{Mac users}\label{mac-users}}
\hypertarget{linux-users}{%
\subsection{Linux users}\label{linux-users}}
\hypertarget{installing-from-r}{%
\section{\texorpdfstring{Installing from \texttt{R}}{Installing from R}}\label{installing-from-r}}
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{remotes}\SpecialCharTok{::}\FunctionTok{install\_github}\NormalTok{(}\StringTok{"NOAA{-}FIMS/FIMS"}\NormalTok{)}
\FunctionTok{library}\NormalTok{(FIMS)}
\end{Highlighting}
\end{Shaded}
\hypertarget{specifying-and-compiling-the-model}{%
\section{Specifying and compiling the model}\label{specifying-and-compiling-the-model}}
You can add components to the model using S4 classes.
\begin{Shaded}
\begin{Highlighting}[]
\CommentTok{\#TODO: add script to populate the model}
\end{Highlighting}
\end{Shaded}
\hypertarget{extracting-model-output}{%
\section{Extracting model output}\label{extracting-model-output}}
Here is how you get the model output.
\begin{Shaded}
\begin{Highlighting}[]
\CommentTok{\#Todo add code for how to extract model output}
\end{Highlighting}
\end{Shaded}
\hypertarget{model-specification}{%
\chapter{Model specification}\label{model-specification}}
This section describes the implementation of the modules in FIMS in milestone 1. For the first milestone, we must implement enough complexity to adequately test a very standard population model. For this reason, we implement the minimum structure that can run the model described in \href{}{Li et al.~2020}.
\hypertarget{model-variables-and-bounds}{%
\section{Model variables and bounds}\label{model-variables-and-bounds}}
\hypertarget{inherited-functors-from-tmb}{%
\section{\texorpdfstring{Inherited functors from \texttt{TMB}}{Inherited functors from TMB}}\label{inherited-functors-from-tmb}}
\hypertarget{atomic-functions}{%
\subsection{Atomic functions}\label{atomic-functions}}
Wherever possible, \texttt{FIMS} should not reinvent atomic functions with extant definitions in \texttt{TMB}. If there is a need for a new atomic function the development team can add it to \texttt{TMB} using the \texttt{TMB\_ATOMIC\_VECTOR\_FUNCTION()} macro following the instructions \href{https://kaskr.github.io/adcomp/_book/AtomicFunctions.html\#example-adding-new-primitive-function-with-known-derivatives}{here}.
\hypertarget{statistical-distributions}{%
\subsection{Statistical distributions}\label{statistical-distributions}}
All of the statistical distributions needed for the first milestone of \texttt{FIMS} are implemented in \texttt{TMB} and need not be replicated.
Code can be found \href{http://kaskr.github.io/adcomp/group__R__style__distribution.html}{here}.
\textbar Distribution \textbar{} Name\textbar{}
\textbar{} ------------\textbar---------\textbar{}
\textbar Normal \textbar{} \href{http://kaskr.github.io/adcomp/dnorm_8hpp.html}{dnorm}\textbar{}
\textbar Multinomial \textbar{} \href{http://kaskr.github.io/adcomp/group__R__style__distribution.html\#gafd0ae6b53840267138bb9250115fbe8b}{dmultinom}\\
\hypertarget{beverton-holt-expected-recruitment-function}{%
\section{Beverton-Holt expected recruitment function}\label{beverton-holt-expected-recruitment-function}}
For parity with existing stock assessment models, the first recruitment option in FIMS is a Beverton-Holt {[}cite{]} parameterized with R0 and h.
\[R_t =\frac{0.8R_0hS_{t-1}}{0.2R_0\phi_0(1-h) + S_{t-1}(h-0.2)}\]
Where \(R_t\) and \(S_t\) are mean recruitment and spawning biomass in time \(t\), \(h\) is Mace-Doonan steepness, and \(\phi_0\) are the unfished spawning biomass per recruit. The initial FIMS model will implement a static spawning biomass-per-recruit function, with the ability to overload the method in the future to allow for time-variation in mortality, maturity, and weight-at-age over time to account for changes in spawning biomass per recruit. Deviations are assumed to be lognormally distributed such that realized recruitment is the product of mean recruitment and the exponentiated recruitment deviation.
\[R_t = R_t\mathrm{exp}(r_{dev,t}-R^2/2), r_{dev,t} \sim N(0,R^2)\]
However, true \(r_{dev,t}\) values are not known, so when using estimated recruitment deviations \(\hat{r_{dev,t}}\) the following equation is applied to calculate mean unbiased recruitment \(R*_t\) using a bias adjustment factor \(b_y=\frac{E[SD(ry)]^2}{\sigma_R^2}\) (Methot and Taylor, 2011).
\[R^*_t=R_t\mathrm{exp}(\hat{r_{dev,t}}-b_y\frac{\sigma_R^2}{2})\]
The recruitment function should take as input the \(R\) , \(S\) values, the \(h\), \(ln(R_0)\), and R parameters and \(\phi_0\) and return mean and realized recruitment.
\hypertarget{logistic-function-with-extensions}{%
\section{Logistic function with extensions}\label{logistic-function-with-extensions}}
\[x_i=\frac{1}{1+\mathrm{exp}(-ln(19)(i-\nu_1)/\nu_2)}\]
Where \(x_i\) is the quantity of interest (proportion mature, selected, etc.), \(i\) is the index (can be age or size or any other quantity),
\(\nu_1\) is the index of 50\% mature and \(\nu_2\) is the difference in the index at 50\% and the index at 95\% (\(\nu_2 = \mathrm{ln}(19)/s\) where
\(s\) is the slope parameter from an alternative parameterization). Logistic functions for maturity and selectivity should inherit and extend
upon the base logistic function implementation.
\hypertarget{catch-and-fishing-mortality}{%
\section{Catch and fishing mortality}\label{catch-and-fishing-mortality}}
The Baranov catch equation relates catch to instantaneous fishing and natural mortality.
\[ C_{f,a,t}=\frac{F_{f,a,t}}{F_{f,a,t}+M}(1-\mathrm{exp}(-(F_{f,a,t}+M)))N_{a,t}\]
Where \(C_{f,a,t}\) is the catch at age \(a\) at time \(t\) for fleet \(f\), \(F\) is instantaneous fishing mortality,
\(M\) is assumed constant over ages and time in the minimum viable assessment model, \(N_a,t\) is the number of
age \(a\) fish at time \(t\).
\[F_{a,t}=\sum_{a=0}^A s_{a,f,t}F\]
\(s_a,f\) is selectivity at age \(a\) for fleet \(f\). Selectivity-at-age is constant over time.
Catch is in metric tons and survey is in number, so calculating catch weight (\(CW_t\)) is done as follows:
\[ CW_t=\sum_{a=0}^A C_{a,t}w_a \]
Survey numbers are calculated as follows
\[I_t=q\sum_{a=0}^AN_{a,t}\]
Where \(I_t\) is the survey index and \(q_t\) is survey catchability at time \(t\).
\hypertarget{modeling-loops}{%
\section{Modeling loops}\label{modeling-loops}}
This tier associates the expected values for each population section associated with a data source to that data source using a likelihood function. These likelihood functions are then combined into an objective function that is passed to TMB.
The population loop will be initialized at a user-specified age, time increment, and seasonal structure, rather than assuming ages, years, or seasons follow any pre-defined structure. Population categories will be described flexibly, such that subpopulations such as unique sexes, stocks, species, or areas can be handled identically to reduce duplication. Each subpopulation will have a unique set of attributes assigned to it, such that each subpopulation can share or have a different functional process (e.g.~recruitment function, size-at-age) than a different category.
Spawning time and recruitment time are user-specified and can occur more than once per year. For the purposes of replicating model comparison project outputs, in milestone 1, all processes including spawning and recruitment occur January 1, but these should be specified via the \texttt{spawn\_time} and \texttt{recruit\_time} inputs into FIMS to allow for future flexibility. Spawning and recruitment timing can be input as a scalar or vector to account for multiple options.
Within the population loop, matrices denoting population properties at different partitions (age, season, sex) are translated into a single, dimension-folded index. A lookup table is computed at model start so that the dimension-folded index can be mapped to its corresponding population partition or time partition (e.g.~population(sex, area, age, species, time, \ldots)) so the programmer can understand what is happening. The model steps through each specified timestep to match the data to expected values, and population processes occur in the closest specified timestep to the user-input process timing (e.g.~recruitment) across a small timestep that is a predefined constant.
\hypertarget{expected-numbers-and-quantities}{%
\section{Expected numbers and quantities}\label{expected-numbers-and-quantities}}
The expected values are calculated as follows in the population.hpp file:
\[ B_t=\sum_{a=0}^AN_{a,t}w_a\]
where \(B_t\) is total biomass in time \(t\), \(N\) is total numbers, \(w_a\) is weight-at-age \(a\) in kilograms.
\[N_t=\sum_{a=0}^AN_{a,t}\]
where \(N_t\) is the total number of fish in time \(t\).
\hypertarget{initial-values}{%
\section{Initial values}\label{initial-values}}
\hypertarget{initial-n}{%
\subsection{Initial N}\label{initial-n}}
\hypertarget{initial-f}{%
\subsection{Initial F}\label{initial-f}}
\hypertarget{likelihood-calculations}{%
\section{Likelihood calculations}\label{likelihood-calculations}}
Age composition likelihood links proportions at age from data to model using a multinomial likelihood function. The multinomial and lognormal distributions, including atomic functions are provided within \texttt{TMB}.
Survey index likelihood links estimated CPUE to input data CPUE in biomass using a lognormal distribution. (model.hpp)
Catch index likelihood links estimated catch to input data catch in biomass using a lognormal distribution. (model.hpp)
Age composition likelihoods link catch-at-age to expected catch-at-age using a multinomial distribution.
\hypertarget{hpp-template-for-c-modules}{%
\chapter{.hpp template for C++ modules}\label{hpp-template-for-c-modules}}
In this section we will describe how to structure a new .hpp file in FIMS.
\begin{Shaded}
\begin{Highlighting}[]
\CommentTok{// tmplate.hpp}
\CommentTok{// Fisheries Integrated Modeling System (FIMS)}
\CommentTok{//define the header gaurd}
\PreprocessorTok{\#ifndef template\_hpp }
\PreprocessorTok{\#define template\_hpp}
\CommentTok{//inherit from model\_base}
\PreprocessorTok{\#include }\ImportTok{"../common.hpp"}\PreprocessorTok{ }
\PreprocessorTok{\#include }\ImportTok{\textless{}iostream\textgreater{}}
\CommentTok{/**}
\CommentTok{ * In this example, we utilize the concept of inheritence and }
\CommentTok{ * polymorphism (https://www.geeksforgeeks.org/polymorphism{-}in{-}c/). All}
\CommentTok{ * classes inherit from model\_base. Name1 and Name2 inherit from NameBase.}
\CommentTok{ * Classes Name1 and Name2 must implement they\textquotesingle{}re own version of }
\CommentTok{ * "virtual T evaluate(const T\& t)", which will have unique logic. }
\CommentTok{ */}
\CommentTok{/*}
\CommentTok{ * fims namespace}
\CommentTok{ */}
\NormalTok{namespace fims}\OperatorTok{\{}
\CommentTok{/**}
\CommentTok{ * NameBase class. Inherits from model\_base.}
\CommentTok{ */}
\NormalTok{template }\OperatorTok{\textless{}}\NormalTok{class T}\OperatorTok{\textgreater{}}
\NormalTok{class NameBase}\OperatorTok{:}\NormalTok{ public model\_base}\OperatorTok{\textless{}}\NormalTok{T}\OperatorTok{\textgreater{}\{} \CommentTok{//note that model\_base gets template parameter T.}
\NormalTok{protected}\OperatorTok{:}
\NormalTok{public}\OperatorTok{:}
\NormalTok{ virtual T Evaluate}\OperatorTok{(}\DataTypeTok{const}\NormalTok{ T}\OperatorTok{\&}\NormalTok{ t}\OperatorTok{)=}\DecValTok{0}\OperatorTok{;} \CommentTok{//"= 0;" means this must be implemented in child.}
\OperatorTok{\};}
\CommentTok{/* }
\CommentTok{* Template class inherits from NameBase}
\CommentTok{*/}
\NormalTok{template }\OperatorTok{\textless{}}\NormalTok{class T}\OperatorTok{\textgreater{}}
\NormalTok{class Name1}\OperatorTok{:}\NormalTok{ public NameBase}\OperatorTok{\textless{}}\NormalTok{T}\OperatorTok{\textgreater{}\{}
\NormalTok{public}\OperatorTok{:}
\CommentTok{/*}
\CommentTok{ *Default constructor}
\CommentTok{ *Initialize any memory here.}
\CommentTok{ */}
\NormalTok{ Name1}\OperatorTok{()\{}
\OperatorTok{\}}
\CommentTok{/**}
\CommentTok{ * Destructor; this method destructs Name1 object.}
\CommentTok{ * Delete any allocated memory here.}
\CommentTok{ */}
\OperatorTok{\textasciitilde{}}\NormalTok{ Name1}\OperatorTok{()\{}
\NormalTok{ std}\OperatorTok{::}\NormalTok{cout }\OperatorTok{\textless{}\textless{}}\StringTok{"I just deleted Name1 object"} \OperatorTok{\textless{}\textless{}}\NormalTok{ std}\OperatorTok{::}\NormalTok{endl}\OperatorTok{;}
\OperatorTok{\}}
\CommentTok{/**}
\CommentTok{ * Note: this function must have the same signature as evaluate in NameBase.}
\CommentTok{ * Overloaded virtual function. This is polymorphism, meaning the }
\CommentTok{ * signature has the same appearance, but the function itself has unique logic.}
\CommentTok{ * }
\CommentTok{ * }\AnnotationTok{@param}\CommentTok{ t}
\CommentTok{ * }\AnnotationTok{@return}\CommentTok{ t+1}
\CommentTok{ */}
\NormalTok{ virtual T Evaluate}\OperatorTok{(}\DataTypeTok{const}\NormalTok{ T}\OperatorTok{\&}\NormalTok{ t}\OperatorTok{)} \OperatorTok{\{}
\NormalTok{ std}\OperatorTok{::}\NormalTok{cout}\OperatorTok{\textless{}\textless{}}\StringTok{"evaluate in Name1 received "}\OperatorTok{\textless{}\textless{}}\NormalTok{t}\OperatorTok{\textless{}\textless{}}
\StringTok{"as a method parameter, returning "}\OperatorTok{\textless{}\textless{}(}\NormalTok{t}\OperatorTok{+}\DecValTok{1}\OperatorTok{)\textless{}\textless{}}\NormalTok{std}\OperatorTok{::}\NormalTok{endl}\OperatorTok{;}
\ControlFlowTok{return}\NormalTok{ t}\OperatorTok{+}\DecValTok{1}\OperatorTok{;} \CommentTok{//unique logic for Name1 class}
\OperatorTok{\}}
\OperatorTok{\};}
\CommentTok{/* }
\CommentTok{* Template class inherits from NameBase}
\CommentTok{*/}
\NormalTok{template }\OperatorTok{\textless{}}\NormalTok{class T}\OperatorTok{\textgreater{}}
\NormalTok{class Name2}\OperatorTok{:}\NormalTok{ public NameBase}\OperatorTok{\textless{}}\NormalTok{T}\OperatorTok{\textgreater{}\{}
\NormalTok{public}\OperatorTok{:}
\CommentTok{/*}
\CommentTok{ *Default constructor.}
\CommentTok{ *Initialize any memory here.}
\CommentTok{ */}
\NormalTok{ Name2}\OperatorTok{()\{}
\OperatorTok{\}}
\CommentTok{/**}
\CommentTok{ * Destructor; this method destructs the Name2 object.}
\CommentTok{ * Delete any allocated memory here.}
\CommentTok{ */}
\OperatorTok{\textasciitilde{}}\NormalTok{ Name2}\OperatorTok{()\{}
\NormalTok{ std}\OperatorTok{::}\NormalTok{cout }\OperatorTok{\textless{}\textless{}}\StringTok{"I just deleted Name2 object"} \OperatorTok{\textless{}\textless{}}\NormalTok{ std}\OperatorTok{::}\NormalTok{endl}\OperatorTok{;}
\OperatorTok{\}}
\CommentTok{/**}
\CommentTok{ * Note: this function must have the same signature as evaluate in NameBase.}
\CommentTok{ * Overloaded virtual function. This is polymorphism, meaning the }
\CommentTok{ * signature has the same appearance, but the function itself has unique logic.}
\CommentTok{ * }
\CommentTok{ * }\AnnotationTok{@param}\CommentTok{ t}
\CommentTok{ * }\AnnotationTok{@return}\CommentTok{ t\^{}2}
\CommentTok{ */}
\NormalTok{ virtual T Evaluate}\OperatorTok{(}\DataTypeTok{const}\NormalTok{ T}\OperatorTok{\&}\NormalTok{ t}\OperatorTok{)} \OperatorTok{\{}
\NormalTok{ std}\OperatorTok{::}\NormalTok{cout}\OperatorTok{\textless{}\textless{}}\StringTok{"evaluate in Name2 received "}\OperatorTok{\textless{}\textless{}}\NormalTok{t}\OperatorTok{\textless{}\textless{}}
\StringTok{"as a method parameter, returning "}\OperatorTok{\textless{}\textless{}(}\NormalTok{t}\OperatorTok{*}\NormalTok{t}\OperatorTok{)\textless{}\textless{}}\NormalTok{std}\OperatorTok{::}\NormalTok{endl}\OperatorTok{;}
\ControlFlowTok{return}\NormalTok{ t}\OperatorTok{*}\NormalTok{t}\OperatorTok{;} \CommentTok{//unique logic for Name2 class}
\OperatorTok{\}}
\OperatorTok{\};}
\CommentTok{/**}
\CommentTok{ * Add additional implementations below.}
\CommentTok{ */}
\OperatorTok{\}} \CommentTok{//end namespace}
\CommentTok{/**}
\CommentTok{ *Example usage:}
\CommentTok{ *}
\CommentTok{ * void main(int argc, char** argv)\{}
\CommentTok{ * NameBase}\KeywordTok{\textless{}double\textgreater{}}\CommentTok{* name = NULL; //pointer to a NameBase object}
\CommentTok{ * Name1}\KeywordTok{\textless{}double\textgreater{}}\CommentTok{ n1; //inherits from NameBase}
\CommentTok{ * Name2}\KeywordTok{\textless{}double\textgreater{}}\CommentTok{ n2; //inherits from NameBase}
\CommentTok{ *}
\CommentTok{ * name = \&n1; //name now points to n1}
\CommentTok{ * name{-}\textgreater{}Evalute(2.0); //unique logic for n1}
\CommentTok{ *}
\CommentTok{ * name = \&n2; //name now points to n2}
\CommentTok{ * name{-}\textgreater{}Evalute(2.0); //unique logic for n2}
\CommentTok{ * \}}
\CommentTok{ *}
\CommentTok{ * Output:}
\CommentTok{ * evaluate in Name1 received 2 as a method parameter, returning 3}
\CommentTok{ * evaluate in Name2 received 2 as a method parameter, returning 4}
\CommentTok{ *}
\CommentTok{ */}
\PreprocessorTok{\#endif }\CommentTok{/*template\_hpp */}
\end{Highlighting}
\end{Shaded}
\hypertarget{test-case-template}{%
\chapter{Test case template}\label{test-case-template}}
In this section we will describe how to write a test case for your FIMS code.
\hypertarget{introduction}{%
\section{Introduction}\label{introduction}}
FIMS testing framework will include different types of testing to make sure that changes to FIMS code are working as expected. The unit and functional tests will be developed during the initial development stage when writing individual functions or modules. After completing development of multiple modules, integration testing will be developed to verify that different modules work well together. Checks will be added in the software to catch user input errors when conducting run-time testing. Regression testing and platform compatibility testing will be executed before pre-releasing FIMS. Beta-testing will be used to gather feedback from users (i.e., members of FIMS implementation team and other users) during the pre-release stage. After releasing the first version of FIMS, the development team will go back to the beginning of the testing cycle and write unit tests when a new feature needs to be implemented. One-off testing will be used for testing new features and fixing user-reported bugs when maintaining FIMS. More details of each type of test can be found in the Glossary section.
FIMS will use GoogleTest to build a C++ unit testing framework and R testthat to build an R testing framework. FIMS will use Google Benchmark to measure the real time and CPU time used for running the produced binaries.
\hypertarget{c-unit-testing-and-benchmarking}{%
\section{C++ unit testing and benchmarking}\label{c-unit-testing-and-benchmarking}}
\hypertarget{requirements}{%
\subsection{Requirements}\label{requirements}}
To use GoogleTest, you will need:
\begin{itemize}
\item
A compatible operating system (e.g.~Windows, masOS, or Linux).
\item
A C++ compiler that supports at least C++ 11 standard or newer (e.g.~gcc 5.0+, clang 5.0+, or MSVC 2015+). For macOS users, Xcode 9.3+ provides clang 5.0.
\item
A build system for building the testing project. \href{https://cmake.org/}{\underline{CMake}} and a compatible build tool such as \href{https://ninja-build.org/}{\underline{Ninja}} are approved softwares by NMFS HQ.
\end{itemize}
\hypertarget{quickstart-for-windows-user}{%
\subsection{Quickstart for Windows user}\label{quickstart-for-windows-user}}
\begin{itemize}
\item
Download \href{https://github.com/Kitware/CMake/releases}{\underline{CMake 3.22.1 (cmake-3.22.1-windows-x86\_64.zip)}} and put the file folder to \texttt{Documents\textbackslash{}Apps} or other preferred folder.
\item
Download \href{https://github.com/ninja-build/ninja/releases}{\underline{ninja v1.10.2 (ninja-win.zip)}} and put the application to \texttt{Documents\textbackslash{}Apps} or other preferred folder.
\item
Search \texttt{Edit\ environment\ variables\ for\ your\ account} and open the \texttt{Environment\ Variables} window.
\item
Click \texttt{Edit...} under the \texttt{User\ variables\ for\ firstname.lastname} section.
\item
Click \texttt{New}, add path to \texttt{cmake-3.22.1-windows-x86\_64\textbackslash{}bin}, add click \texttt{OK}.
\item