Chapter 3 FIMS Project Overview

3.1 FIMS Governance

The FIMS Terms of Reference describes the high level organization of the FIMS Project. Additional details on roles and responsibilities are provided here.

3.1.1 Developers

Developers are expected to adhere to the principles and guidelines outlined within this handbook, including the Code of Conduct, Contributer Guidelines, Style Guide, Issue Tracking, and Test Case Template.

3.1.2 C++ developers

The C++ developer responsibilities include:

  • Writing the module code.
  • Creating documentation for the module and building the documentation in doxygen to ensure it is error-free.
  • Implementing the suite of required test cases in Google Test for the module.
  • Ensuring the module runs through the FIMS Github actions.

Once development of a bug fix or a new component of FIMS is complete, the developer should create a 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.

3.1.3 R developers

The R developers responsibilities include:

  • Writing the Rcpp interface to the C++ code.
  • Writing Roxygen documentation for any R functions
  • Writing testthat() test cases for any R functionality
  • Ensuring the code passes the R CMD CHECK, styler, and any other automated checks.

Once these are complete, the developer should create a 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.

3.1.4 Reviewers

The reviewers are responsible for adhering to documented guidelines in the Code Review section. Reviewers should confirm that the new code is able to build and run within their own development environment as well as via the Github actions on the repository. 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.

3.1.5 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 status dashboard.

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

3.1.7 Lead of Test Development

The Lead of Test Development is responsible for ensuring development of test objectives, test strategies and test plans of the FIMS product at subsequent milestones. The lead of Test Development will identify the tools for test reporting, management and automation, guide and monitor the design, implementation, and execution of test cases and test procedures.

3.1.8 Lead of Research & Development

The Lead of Research & Development oversees the investigations into stock assessment modeling best practices that spans the scope of computer science, statistical inference, and population and community modeling. Provides methods and guidelines for prioritizing features to be incorporated into subsequent milestones.

3.1.9 Code of Conduct Enforcement

The Code of Conduct enforcer is responsible for responding to allegations of 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.

3.1.10 External Collaborators

External collaborators interested in contributing to FIMS development are required to clone or 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 development. 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 clone the repository and 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.

3.2 FIMS Development Cycle

FIMS is structured as an agile software development process with live development on the web and Github. The development process cycles through a planning, analysis, and design phase leading to the establishment of a developmental Milestone. The implementation phase is made up of several development sprints that meet the objectives of the established Milestone. This is followed by testing & integration and a maintenance phase before the cycle starts over again. FIMS is currently in the implementation phase of Milestone 1. See M1 model specification for a description of the model.

FIMS Development Cycle. Current development stage is the implementation phase of Milestone 1

Figure 3.1: FIMS Development Cycle. Current development stage is the implementation phase of Milestone 1

3.2.1 Issue Lifecycle

FIMS development will adhere to a lifecycle for issues that makes it clear which issues can be resolved when.

  • 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: needs-triage. A issue is not considered Active until this label is removed.
  • Activation — When the 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 needs-triage label is applied again. An issue is Active from the time it is Activated until reaches Resolution.
  • 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.
  • 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.
  • 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.
  • 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.
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.

Figure 3.2: 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.

3.2.2 Feature Validation

FIMS uses a standardized set of criteria to prioritize and determine which features will be incorporated into the next development milestone.

TODO: add criteria (to be defined) used to prioritize features for future milestones

3.3 GitHub Collaborative Environment

Communication is managed via the NOAA-FIMS Github organization.

3.3.1 FIMS Branching Strategy

There are several 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 Scaled Trunk Based Development branching strategy to make tasks easier without compromising quality.

Scaled Trunk Based Development; image credit: https://reviewpad.com/blog/github-flow-trunk-based-development-and-code-reviews/

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:

  • Short-lived branches to minimize stale code and merge conflicts
  • Fast release times, especially for bug fixes
  • Ability to release bug fixes without new features

3.3.2 Branch Protection

Branch protection allows for searching branch names with 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.