Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
166 lines (105 loc) · 5.12 KB

CONTRIBUTING.md

File metadata and controls

166 lines (105 loc) · 5.12 KB

Contributing to NineToothed

Thank you for your interest in contributing to NineToothed! This document provides guidelines and instructions for contributing to this project.

Note: This guide is still being actively improved.

Reporting Issues

If you find a bug or have a feature request, please open an issue on GitHub Issues. When reporting a bug, include:

  • A clear description of the problem.
  • Steps to reproduce the issue.
  • Expected vs. actual behavior.
  • Your environment (Python version, OS, GPU, etc.).

Development Environment Setup

  1. Fork and clone the repository:

    git clone https://github.com/InfiniTensor/ninetoothed.git
cd ninetoothed

  2. Install the package in editable mode with all optional dependencies:

    pip install -e .[all]

  3. Install development dependencies:

    pip install -r requirements.txt

  4. Set up Git hooks:

    git config core.hooksPath .githooks

    This enables the project's commit message validation and branch name checks.

Code Development Workflow

We follow GitHub flow. The main steps are:

  1. Create a branch.
  2. Make changes.
  3. Create a pull request (PR).
  4. Address review comments.
  5. Merge the PR.
  6. Delete the branch.

Branch Naming

Use kebab-case (lowercase letters, numbers, and hyphens) for branch names, with a maximum of 50 characters. This is enforced by the pre-push hook.

  • Valid: develop-visualization, fix-123-memory-leak, add-conv2d-support
  • Invalid: Develop_Visualization, fix_memory_leak, myBranch

Commit Messages and PR Titles

The following rules apply to both commit messages and PR titles:

  • Capitalize the first letter.
  • Do not end with punctuation (., !, ?, etc.).
  • Use imperative mood (e.g., "Add feature" not "Added feature").

These rules are enforced by the commit-msg hook.

Valid examples:

  • Add user authentication
  • Fix memory leak in tensor allocation
  • Refactor code generation module

Invalid examples:

  • add user authentication (lowercase)
  • Fix memory leak. (trailing punctuation)
  • Added user authentication (past tense)

Pull Request Requirements

Before merging a PR, you must provide the pytest output in the PR description to confirm that all tests pass with your latest changes. The PR template includes a section for this. See #30 for a reference example.

Code Style Guide

Follow PEP 8 as the primary style guide. For anything PEP 8 does not cover in detail, refer to the GDScript style guide—while it targets a different language, its non-syntax conventions are still applicable.

Run Ruff before every commit:

ruff format && ruff check

This is also enforced by the commit-msg hook.

Additional Rules

  1. Comments should be complete English sentences, starting with a capital letter and ending with punctuation. Use Markdown syntax when referencing code within comments.

  2. Error messages and framework conventions: When a framework has an established convention (e.g., pytest.skip messages are typically lowercase without a trailing period), follow that convention. Otherwise, use the same rules as comments.

  3. Function signatures: If a function has no docstring or comment, do not add a blank line between the function signature and the function body.

  4. Blank lines around control flow: Add a blank line before and after if, for, and similar statements.

  5. Return statements: Add a blank line before a return statement, unless it directly follows a control flow statement like if or for.

  6. Docstrings: Follow PEP 257 conventions.

Running Tests and Linting

Run the test suite:

pytest

Run the linter:

ruff check

Run the formatter:

ruff format

To run a full local CI check before pushing:

ruff format && ruff check && pytest

Version Release Process

This section is primarily for maintainers.

  1. Create an increment-version-number branch and update the version field in pyproject.toml. Follow Semantic Versioning 2.0.0 for version numbers.

  2. Merge the branch via the standard code development workflow.

  3. Create a tag on the master branch using the newly merged commit:

    git checkout master
git pull origin master
git tag -a v<major>.<minor>.<patch> -m "NineToothed version <major>.<minor>.<patch>"

  4. Push the tag to the remote repository:

    git push origin v<major>.<minor>.<patch>

  5. Verify the release by checking: