Contributing to MHKiT-MATLAB

Thank you for your interest in contributing to MHKiT-MATLAB! This guide will help you get started with contributing code, documentation, and bug fixes.

Quickstart

Here's the high-level contribution workflow:

Fork the MHKiT-MATLAB repository
Set up your development environment (Python + MATLAB)
Create a feature branch from develop
Write your code with proper docstrings and tests
Test locally using the docstring checker and unit tests
Add an entry to changelog.md
Push your changes and open a pull request to develop
CI runs automated tests across all supported MATLAB/Python versions
Address review feedback from maintainers
Merge into develop once approved

Fork and Setup

Fork the Repository

Fork the repository on GitHub: https://github.com/MHKiT-Software/MHKiT-MATLAB

Clone your fork to your local machine:

git clone https://github.com/YOUR-USERNAME/MHKiT-MATLAB.git
cd MHKiT-MATLAB

Add upstream as a remote:

git remote add upstream https://github.com/MHKiT-Software/MHKiT-MATLAB.git

Development Environment Setup

See INSTALL.md for detailed instructions on setting up your development environment with MATLAB and MHKiT-Python.

Development Workflow

Branching Strategy

master - Production releases only
develop - Main development branch ← target your PRs here

Creating a Feature Branch

Sync with upstream:

git checkout develop
git fetch upstream
git merge upstream/develop

Create your feature branch:

git checkout -b feature/your-feature-name

Make changes and commit regularly:

git add .
git commit -m "Brief description of changes"

Keep your branch updated:

git fetch upstream
git rebase upstream/develop

Writing Code

Documentation

Docstring Format

All public functions must have properly formatted docstrings. This is loosely enforced by automated CI checks. Where a specific format is not specified, developers should use the template below as a guide.

Docstring Function Template

function result = descriptive_function_name(input_1, input_2, input_3)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Brief one-line description of what the function does
%
% Optional extended description paragraph. Can span multiple lines
% to provide additional context, mathematical background, data sources,
% or important behavioral notes about the function.
%
% Parameters
% ------------
% input_1 : type [units]
%   Description of first parameter. Can span multiple lines.
%   Additional details aligned with first line. Use two spaces for indentation
%     input_1.fieldname_1 : type [units]
%       Description of field
%     input_1.fieldname_2 : type [units]
%       Description of field
% input_2 : type [units]
%   Description of second parameter
% input_t : type [units] (optional)
%   Description of second parameter. Mark optional parameters
%   with (optional) after the type.
%
% Returns
% ---------
% output : type
%   Description of return value. For structure outputs,
%   document nested fields with indentation:
%     output.field1 : type [units]
%       Field 1 description
%     output.field2 : type [units]
%       Field description
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

arguments (Input)
    input_1 struct
    input_2 {mustBeInteger, mustBePositive}
    input_3 {mustBeInteger} = 2
end

arguments (Output)
    result struct
end

% Function implementation goes here

end

Use the `arguments` Block

All functions must use MATLAB's arguments block for input/output type validation.

Simple Example

function result = calculate_energy(power, duration)

arguments
    power double {mustBeNumeric, mustBeFinite}
    duration double {mustBePositive}
end

% Function implementation
result = power * duration;

end

Complex Example (Struct Inputs/Outputs)

function mspl = band_sound_pressure_level(spsd, octave, base, fmin, fmax)

arguments (Input)
    spsd struct
    octave {mustBeInteger, mustBePositive}
    base {mustBeInteger} = 2
    fmin {mustBeNumeric, mustBePositive} = 10
    fmax {mustBeNumeric, mustBePositive} = 100000
end

arguments (Output)
    mspl struct
end

% Function implementation
mspl = struct();

end

Common Validation Functions

mustBeNumeric - Must be numeric type
mustBeFinite - No NaN or Inf values
mustBePositive - Greater than zero
mustBeInteger - Integer values only
mustBeNonzero - Cannot be zero
mustBeNonempty - Cannot be empty

For custom validation, create functions in mhkit/utils/ or module-specific directories.

Checking Your Docstrings

Before submitting your PR, there is a python script to validate docstrings locally:

# Check all mhkit files
python scripts/check_docstrings.py

# Check specific directory
python scripts/check_docstrings.py --path mhkit/wave

# Verbose output
python scripts/check_docstrings.py --verbose

Note: The docstring checker actions run automatically on all PRs. Errors must be fixed before merging to develop and master.

Testing

Running Tests Locally

Before submitting your PR, run the full test suite:

% Navigate to tests directory
cd mhkit/tests

% Run all tests
runTests

Writing Unit Tests

When adding new functionality, create tests in mhkit/tests/:

Use the patterns in the existing test files as a guide.

Test coverage should include:

Normal operation
Edge cases
Error conditions
Optional parameters

Changelog

All contributions must include a changelog entry.

Adding a Changelog Entry

Open changelog.md
Add your entry at the top under a new "Unreleased" section (if it doesn't exist):

# Unreleased

## PR #XXX - Brief Feature Description

- Author: @your-github-username
- Description of changes
- Key additions:
  - Bullet point 1
  - Bullet point 2

[rest of existing changelog...]

Changelog Format Guidelines

Use format: ## PR #XXX - Title
Include your GitHub username
List key changes as bullet points
Reference related issues if applicable
Place at the top of the file

Example:

# Unreleased

## PR #185 - Add Wave Spectral Analysis Functions

- Author: @contributor
- Added native MATLAB implementations for wave spectral analysis
- Key additions:
  - `wave/resource/wave_spectral_moment.m` - Calculate spectral moments
  - `wave/resource/wave_spectral_bandwidth.m` - Calculate spectral bandwidth
  - Unit tests and example live script
- Closes #180

Submitting Your PR

Pull Request Process

Push your changes to your fork:

git push origin feature/your-feature-name

Create a pull request:
- Go to https://github.com/MHKiT-Software/MHKiT-MATLAB
- Click "New Pull Request"
- Base branch: develop ← Important!
- Compare branch: your feature branch
- Provide a clear description of your changes
PR requirements:
- Target develop branch (NOT master)
- All CI checks must pass:
  - Docstring validation
  - Unit tests (Linux, macOS, Windows)
  - Code compatibility checks
- Changelog entry added
- Tests added/updated for new functionality
After submission:
- CI will automatically test across all supported MATLAB/Python versions
- Address any review feedback
- Once approved, maintainers will merge to develop

Note: Sometimes github actions fail for non code related reasons. If this happens, please reach out in the discussions or issues page. It is a reasonable procedure to re-run failed actions, and possibly disable failing combinations of matlab/python versions if they are not critical.

PR Title Format

Use conventional commit format:

Feature: Add wave spectral bandwidth calculation
<module>: Correct NDBC data parsing for missing values
Actions: Fix action related bug
Examples: Fix typo in acoustics example
Fix: Incorrect sign in energy calculation

Code Standards

Style: Use the templates provided above to ensure functions follow consistent style
Clarity: Use meaningful variable names with units, i.e. significant_wave_height_meters over shorter variables like hm0.
Comments: Use comments to explain complex logic, but avoid obvious comments
Testing: Include unit tests

Getting Help

Documentation: https://mhkit-software.github.io/MHKiT/
Issues: https://github.com/MHKiT-Software/MHKiT-MATLAB/issues
Discussions: https://github.com/MHKiT-Software/MHKiT-MATLAB/discussions

License

By contributing, you agree that your contributions will be licensed under the Revised BSD License. See LICENSE for details.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to MHKiT-MATLAB

Quickstart

Fork and Setup

Fork the Repository

Development Environment Setup

Development Workflow

Branching Strategy

Creating a Feature Branch

Writing Code

Documentation

Docstring Format

Docstring Function Template

Use the `arguments` Block

Simple Example

Complex Example (Struct Inputs/Outputs)

Common Validation Functions

Checking Your Docstrings

Testing

Running Tests Locally

Writing Unit Tests

Changelog

Adding a Changelog Entry

Changelog Format Guidelines

Submitting Your PR

Pull Request Process

PR Title Format

Code Standards

Getting Help

License

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to MHKiT-MATLAB

Quickstart

Fork and Setup

Fork the Repository

Development Environment Setup

Development Workflow

Branching Strategy

Creating a Feature Branch

Writing Code

Documentation

Docstring Format

Docstring Function Template

Use the arguments Block

Simple Example

Complex Example (Struct Inputs/Outputs)

Common Validation Functions

Checking Your Docstrings

Testing

Running Tests Locally

Writing Unit Tests

Changelog

Adding a Changelog Entry

Changelog Format Guidelines

Submitting Your PR

Pull Request Process

PR Title Format

Code Standards

Getting Help

License

Use the `arguments` Block