Contribution Guidelines

This guide tracks the current repository workflow and follows the same upcoming release baseline as the rest of the docs: 0.2.11.

To Contributors

We warmly welcome developers familiar with various scientific computing libraries related to numerical calculus to join the project, contribute code, and share their valuable experiences. At the same time, we encourage beginners to learn and master numerical methods related to calculus by participating in development and improving documentation. In this project, we hope that both experienced developers and beginners can find contribution goals that interest them by reviewing the project's documentation, tables, and code examples.

We sincerely thank all the developers who have contributed to this project. Whether through submitting code, improving documentation, or providing valuable feedback, every effort you make helps to make this project better. Your enthusiasm and wisdom in the development process continually drive the project forward, and bring more opportunities for collaboration within the community. We appreciate your support and dedication, and we look forward to achieving more together, driving this project toward an even brighter future!

Table of Contents

1. Code Style
2. Naming Conventions 2.1 Variable Naming 2.2 Function Naming 2.3 Struct and Trait Naming 2.4 Constant Naming 2.5 Result Err Construction and Err Code
3. Comments
4. File Standards 4.1 Folder Naming 4.2 File Organization
5. Commit Guidelines 5.1 Commit Messages 5.2 Commit Frequency
6. Code Review

1. Code Style

• The project follows the formatting style enforced by the MoonBit Toolchain. Format your code automatically using the following command:

  moon fmt

  Ensure that you run moon fmt before committing your code to maintain consistency.

  Alternatively, you can use the ready_to_pr.sh script to automatically format the code, run checks, generate test coverage files, and create .mbti files.

• Prefer using-imported names over fully-qualified package calls when the imported names are used repeatedly in a file.

  Preferred:

  using @internal { ensure_square, ensure_mul_compatible, trait HasShape }

  Avoid repeated forms such as:

  @internal.ensure_square(self)
  @internal.ensure_mul_compatible(a, b)

• Avoid introducing new direct dependencies on moonbitlang/core/immut/array helpers when an equivalent immut/vector-level helper or local wrapper already exists. Prefer the project-level abstraction over the raw package helper.

2. Naming Conventions

2.1 Variable Naming

• Use lowercase letters with underscores as separators (e.g., my_var).
• Variable names should be descriptive and clearly indicate their purpose.

2.2 Function Naming

• Use lowercase letters with underscores as separators (e.g., calc_total_price()).
• Function names should be concise and descriptive, clearly expressing their functionality.

2.3 Struct and Trait Naming

• Use PascalCase (e.g., MyStruct, MyTrait).
• Names should intuitively reflect the function or role of the struct or trait, avoiding overly abstract or non-descriptive names.

2.4 Constant Naming

• Note: In the MoonBit context, "variables" are typically referred to as "bindings" and are immutable by default unless marked with mut. Thus, there is no strict distinction between constant and variable naming.
• Use lowercase letters with underscores as separators (e.g., machine_dbl_epsilon).
• Prefix constants with a descriptive category where applicable (e.g., machine_dbl_epsilon, where machine indicates a machine-related constant).
• Constant names should be concise and descriptive to facilitate understanding.

2.5 Result Err Construction and Err Code

• Use uppercase letters with underscores as separators (e.g., E_MAX_ITER).
• Err codes should be prefixed with E to indicate an error-related construct.
• Err codes should be concise and descriptive for easy comprehension.

3. Comments

• Conciseness: Comments should be clear and to the point, avoiding unnecessary verbosity.
• Consistency: Use uniform terminology and style across the codebase.
• Clarity: Ensure comments are easy to understand, avoiding complex jargon or ambiguous wording.
• Accuracy: Comments must accurately reflect the functionality and purpose of the code.
• Up-to-date: Comments should be updated alongside code changes to maintain relevance.

Developers are encouraged to use MoonBit LSP’s AI-generated code comments to improve efficiency, but AI-generated comments should be reviewed to ensure correctness.

4. File Standards

4.1 Folder Naming

• Use lowercase letters for folder names.

• Folder names should be concise, descriptive, and separated using underscores (_). Avoid numbers and special characters.

  Examples:

  • For differentiation-related functionality: diff
  • For derivative-related functionality: deriv

4.2 File Organization

• Files should be organized based on functionality, with each file focusing on a specific feature. Use lowercase letters with underscores for file names.

• File names should be descriptive and clearly indicate the core functionality they implement.

  Examples:

  • gauss_kronrod.mbt: Implements Gaussian quadrature with Kronrod extension.
  • adaptive_quadrature_gk.mbt: Implements adaptive quadrature using Gaussian quadrature with Kronrod extension.

• Note: Avoid overly generic or vague file names such as utils.mbt. Instead, ensure file names correspond to their function or module.

5. Commit Guidelines

5.1 Commit Messages

• Use the ready_to_pr.sh script before committing to format code, run checks, generate test coverage files, and create .mbti files.

• Each commit should have a clear description of the changes made.

• Commit messages should be in English, concise, and precise.

• Use prefixes such as fix:, feat:, refactor:, and doc: to indicate the type of change.

  Examples:

  fix: fix bug in something
  feat: add feature for something
  refactor: refactor something
  doc: add docs for something

5.2 Commit Frequency

• Keep commits small and focused on a single feature or fix.
• Avoid large, monolithic commits that include multiple unrelated changes.

5.3 Release Checklist

• Before publishing to mooncakes, make sure moon.mod has already been bumped to the intended unreleased version.
• Update README.md if the current package summary or release notes no longer match the repository state.
• Run moon check and ./run_test.sh locally before publishing.
• The GitHub Actions publish workflow reads the release version directly from moon.mod.
• If mooncakes reports a duplicate version, do not retry the same version. Bump the version first.

6. Code Review

• If you are not a maintainer or collaborator, contact them before modifying dependencies or version numbers in moon.mod.
• All code submissions must undergo code review.
• Code reviews should focus on code quality, style, performance, and security.
• Reviewers should provide constructive feedback to improve the code.