CloudNebulaProject/barycenter
1
0
Fork 0
mirror of https://github.com/CloudNebulaProject/barycenter.git synced 2026-04-10 13:10:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
barycenter/CONTRIBUTING.md
Till Wegmueller 9244d60368
build(ci): switch to cargo nextest for testing 
Problem:
- cargo test runs integration tests in parallel in the same process
- This causes port conflicts when multiple tests try to start servers
- CI tests were failing with "Server failed to start within timeout"

Solution:
- Switch to cargo-nextest which runs tests in separate processes
- This provides better test isolation and prevents port conflicts

Changes:
- CI: Install and use cargo-nextest instead of cargo test
- README.md: Document nextest usage with installation instructions
- CONTRIBUTING.md: Add prominent note about using nextest
- CLAUDE.md: Add critical reminder section about nextest requirement

Why nextest:
- Tests run in separate processes (no port conflicts)
- Better test isolation and reliability
- Cleaner output and better performance
- Industry best practice for Rust integration testing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-29 14:01:26 +01:00

6.5 KiB
Raw Blame History

Contributing to Barycenter

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

Code of Conduct

Be respectful, inclusive, and collaborative. We're here to build great software together.

Development Workflow

We use Gitflow as our branching model. Please familiarize yourself with this workflow before contributing.

Branch Structure

Main Branches

  • main - Production-ready code. Only release and hotfix branches merge here.
  • develop - Integration branch for features. Default branch for development.

Supporting Branches

  • feature/* - New features and non-emergency bug fixes
  • release/* - Release preparation (version bumps, final testing)
  • hotfix/* - Emergency fixes for production issues

Workflow Steps

Working on a New Feature

  1. Create a feature branch from develop:

    git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

  2. Make your changes following our commit conventions (see below)

  3. Push your branch:

    git push -u origin feature/your-feature-name

  4. Create a Pull Request targeting develop

Creating a Release

  1. Create a release branch from develop:

    git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

  2. Update version numbers and finalize changelog

  3. Create PR to main and after merge, tag the release:

    git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

  4. Merge back to develop to include any release changes

Hotfix Process

  1. Create a hotfix branch from main:

    git checkout main
git pull origin main
git checkout -b hotfix/v1.2.1

  2. Fix the issue and update version number

  3. Create PR to main and after merge, tag the hotfix

  4. Merge back to develop to include the fix

Commit Message Convention

We follow Conventional Commits specification. This leads to more readable commit history and enables automated changelog generation.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Type

Must be one of the following:

  • feat - A new feature
  • fix - A bug fix
  • docs - Documentation only changes
  • style - Changes that don't affect code meaning (formatting, whitespace)
  • refactor - Code change that neither fixes a bug nor adds a feature
  • perf - Performance improvement
  • test - Adding or updating tests
  • build - Changes to build system or dependencies
  • ci - Changes to CI configuration files and scripts
  • chore - Other changes that don't modify src or test files
  • revert - Reverts a previous commit

Scope (Optional)

The scope should specify the place of the commit change:

  • auth - Authentication/authorization
  • token - Token endpoint and generation
  • jwks - Key management and JWKS
  • storage - Database and storage layer
  • config - Configuration management
  • web - Web server and routing
  • oidc - OpenID Connect specific features
  • oauth - OAuth 2.0 specific features

Subject

  • Use imperative, present tense: "add" not "added" nor "adds"
  • Don't capitalize first letter
  • No period (.) at the end
  • Maximum 50 characters

Body (Optional)

  • Explain what and why (not how)
  • Wrap at 72 characters
  • Separate from subject with a blank line

Footer (Optional)

  • Reference issues: Closes #123 or Fixes #456
  • Note breaking changes: BREAKING CHANGE: description

Examples

Simple Feature

feat(auth): add PKCE S256 support

Implements code_challenge and code_verifier validation
according to RFC 7636.

Closes #42

Bug Fix

fix(token): validate token expiration correctly

Token validation was not properly checking the exp claim
against current time, allowing expired tokens to be used.

Breaking Change

feat(config)!: change database configuration format

BREAKING CHANGE: Database connection string now requires
explicit mode parameter. Update config.toml:

Old: connection_string = "sqlite://db.sqlite"
New: connection_string = "sqlite://db.sqlite?mode=rwc"

Documentation

docs: update README with configuration examples

Multiple Changes

refactor(storage): simplify client lookup logic

- Remove redundant database queries
- Add connection pooling
- Improve error messages

Related to #78

Pull Request Process

  1. Update documentation if you're changing functionality
  2. Add tests for new features or bug fixes
  3. Ensure all tests pass: cargo test
  4. Ensure code compiles: cargo check
  5. Format your code: cargo fmt
  6. Run clippy: cargo clippy
  7. Update CHANGELOG.md if applicable
  8. Reference related issues in the PR description
  9. Request review from maintainers

PR Title

PR titles should also follow Conventional Commits format:

feat(auth): implement social login providers
fix(token): correct ID token expiration handling
docs: update API endpoint documentation

Code Style

  • Follow Rust standard style guidelines
  • Run cargo fmt before committing
  • Address cargo clippy warnings
  • Use meaningful variable and function names
  • Add comments for complex logic
  • Keep functions focused and small

Testing

IMPORTANT: We use cargo nextest for running tests, not cargo test.

Nextest runs tests in separate processes, which prevents port conflicts and other issues when running integration tests in parallel.

  • Write unit tests for new functions
  • Add integration tests for new endpoints
  • Test both success and error cases
  • Aim for meaningful test coverage

Installing nextest

cargo install cargo-nextest

Running Tests

# Run all tests
cargo nextest run

# Run specific test
cargo nextest run test_name

# Run with verbose output
cargo nextest run --verbose

# Run in release mode
cargo nextest run --release

Documentation

  • Update CLAUDE.md for significant architectural changes
  • Document all public APIs
  • Include examples in documentation
  • Update README.md for user-facing changes

Questions or Problems?

  • Open an issue for bugs or feature requests
  • Tag issues appropriately (bug, enhancement, question)
  • Provide detailed reproduction steps for bugs
  • Search existing issues before creating new ones

License

By contributing, you agree that your contributions will be licensed under the same license as the project.