Contributing¶

Note

This project is currently in closed beta. We are not accepting external contributions at this time. This guide is intended for IBM contributors only.

For IBM Contributors¶

This guide provides development setup and coding standards for IBM contributors working on Algorithm Nexus during the closed beta phase.

If you would like to fix a bug, please raise an issue before sending a pull request so it can be tracked.

Merge approval¶

The project maintainers use LGTM (Looks Good To Me) in comments on the code review to indicate acceptance. A change requires LGTMs from one of the maintainers.

For a list of the maintainers, see the MAINTAINERS.md page.

Legal¶

Each source file must include a license header for the MIT License. Using the SPDX format is the simplest approach. e.g.

# Copyright IBM Corporation 2025, 2026
# SPDX-License-Identifier: Apache-2.0

We have tried to make it as easy as possible to make contributions. This applies to how we handle the legal aspects of contribution. We use the same approach - the Developer's Certificate of Origin 1.1 (DCO) - that the Linux® Kernel community uses to manage code contributions.

We simply ask that when submitting a patch for review, the developer must include a sign-off statement in the commit message.

Here is an example Signed-off-by line, which indicates that the submitter accepts the DCO:

Signed-off-by: John Doe <john.doe@example.com>

You can include this automatically when you commit a change to your local git repository using the following command:

git commit -s

Communication¶

You can get in touch with us by starting a discussion on GitHub.

Commit and PR title guidelines¶

We require commits and PR titles to conform to the conventional commits standard and follow the Angular convention. In a nutshell, the commit message should be structured as follows:

Tip

It is highly recommended to include the scope in the PR title and in all the commits.

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Where type is one of the following:

build: Changes that affect the build system (e.g., pyproject.toml files, Dockerfiles, etc.) or external dependencies.
ci: Changes to CI-related configuration files and scripts
docs: Documentation only changes
feat: A new feature
fix: A bug fix
perf: A code change that improves performance
refactor: A code change that neither fixes a bug nor adds a feature
style: Changes that do not affect the meaning of the code (white-space, formatting, etc)
test: Adding missing tests or correcting existing tests
chore (discouraged): Minor changes that don't fit in other categories

Coding style guidelines¶

We require code and markup to adhere to certain rules. We enforce these rules through the following tools:

Ruff - Python linting
uv - Dependency management
Copywrite - License header management
Markdownlint-cli2 - Markdown linting
Yamlfmt - YAML formatting

Before submitting a pull request, you must ensure that all of the following checks pass.

Using Pre-commit Hooks (Recommended)¶

We provide pre-commit hooks that automatically run these checks before each commit. To set up pre-commit hooks:

Install development dependencies (includes pre-commit and all linting tools):
```
uv sync --group dev
```

Install the git hook scripts:

pre-commit install --install-hooks
pre-commit install --hook-type commit-msg

(Optional) Run against all files:
```
pre-commit run --all-files
```

Once installed, the hooks will run automatically on git commit. If any checks fail, the commit will be aborted and you'll need to fix the issues before committing again.