Skip to content

Latest commit

 

History

History
121 lines (81 loc) · 3.16 KB

CONTRIBUTING.md

File metadata and controls

121 lines (81 loc) · 3.16 KB

Contributing to Soar

Thank you for your interest in contributing to Soar! This document provides guidelines to help make the contribution process smooth and effective for everyone involved.

Table of Contents

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally
git clone https://github.com/YOUR-USERNAME/soar.git
cd soar
  1. Add the upstream remote
git remote add upstream https://github.com/pkgforge/soar.git

Development Workflow

  1. Create a new branch for your feature or bugfix

  2. Make your changes

  3. Keep your branch updated with the main branch:

git pull upstream main --rebase

Commit Guidelines

We follow the Conventional Commits specification for our commit messages. This leads to more readable messages that are easy to follow when looking through the project history.

Commit Message Format

Each commit message consists of a header, a body and a footer:

<type>(<scope>): <short summary>

<body>

<footer>

The header is mandatory and must conform to the following format (can be ignored if you expect the commits to be squashed):

  • type: Describes the kind of change:

    • feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

  • scope: Can be anything specifying the place of the commit change (e.g., cli, repo, package)

  • summary: Summary in present tense, not capitalized, no period at the end, under 72 characters

Examples

feat(cli): add search filtering by package type

fix(repo): resolve metadata caching issue

The metadata cache wasn't properly invalidated when repository 
sources changed, leading to stale package information. This fix 
ensures the cache is rebuilt whenever source files are modified.

Fixes #123

Commit Practices to Avoid

  • Don't use AI-generated commit messages without review and editing
  • Don't make vague commits like "bug fix" or "update"

Pull Request Process

  1. Ensure your code compiles before opening a PR
  2. Reference any relevant issues in your PR description

Draft Pull Requests

If you have work in progress that you want early feedback on, or if there are known blockers:

  1. Open the PR as a Draft
  2. Clearly mention in the description that it's a work in progress
  3. Describe the specific blockers or areas where you need help
  4. Convert to a regular PR once ready for final review

Code Style and Quality

General Guidelines

  • Use meaningful variable and function names
  • Document complex algorithms or non-obvious code decisions
  • Avoid AI-generated comments - we prefer contextual comments over boilerplate generated by tools like Cursor or Copilot

Quality Checks

Before submitting a PR:

  1. Ensure your code compiles with no warnings
  2. Optionally, run cargo clippy and address any lints
  3. Format your code with cargo fmt