4. Contributing to HepSW¶

Thank you for your interest in contributing to HepSW! This guide will help you get started with contributing to the project.

4.1. Ways to Contribute¶

There are several ways you can contribute to HepSW:

Add Package Manifests: Contribute new package manifests to the HepSW Package Index Repository (HPIR)
Improve Documentation: Help improve or translate documentation
Report Bugs: Submit bug reports and issues
Suggest Features: Propose new features or improvements
Fix Bugs: Submit pull requests to fix existing issues
Code Contributions: Contribute to the HepSW core codebase

4.2. Contributing Package Manifests¶

The most common contribution is adding new package manifests to HPIR.

4.2.1. Prerequisites¶

Familiarity with YAML syntax
Understanding of the package’s build system
Knowledge of the package’s dependencies
A GitHub account

4.2.2. Process¶

Fork the HPIR repository:

# Visit https://github.com/thisismeamir/hepsw-package-index/
# Click "Fork" button

Clone your fork:

git clone https://github.com/YOUR-USERNAME/hepsw-package-index.git
cd hepsw-package-index

Create a new branch:
```
git checkout -b add-package-name
```

Create the manifest:

mkdir -p packages/package-name
cd packages/package-name
# Create manifest.yaml

Write the manifest:

name: package-name
version: x.y.z
description: A brief description of the package

source:
  type: tarball
  url: https://example.com/package-name-x.y.z.tar.gz
  checksum: sha256:actual-checksum-here

specifications:
  build:
    toolchain:
      - cmake >=3.15
    dependencies:
      - name: dependency-name
        version: ">=1.0.0"

recipe:
  configure:
    - name: Configure
      type: cmake
      args:
        - -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX}
  build:
    - name: Build
      type: cmake
      target: build
      parallel: ${NCORES}
  install:
    - name: Install
      type: cmake
      target: install

Test your manifest locally:

# From your HepSW workspace
hepsw fetch --third-party /path/to/your/manifest.yaml
hepsw evaluate package-name
hepsw walk package-name
hepsw build package-name

Commit and push:

git add packages/package-name/manifest.yaml
git commit -m "Add manifest for package-name version x.y.z"
git push origin add-package-name

Create a Pull Request:
- Go to your fork on GitHub
- Click “Pull Request”
- Describe what package you’re adding and any relevant notes
- Submit the PR

4.2.3. Manifest Guidelines¶

Completeness: Include all required fields (name, version, description, source)
Checksums: Always include SHA-256 checksums for sources
Dependencies: List all build and runtime dependencies with version constraints
Testing: Test the manifest on at least one platform before submitting
Documentation: Add comments for non-obvious configuration options
Versioning: Use semantic versioning (major.minor.patch)
Source URLs: Use stable, official sources (prefer official repositories or releases)

4.2.4. Checklist Before Submitting¶

[ ] Manifest follows the correct YAML structure
[ ] hepsw evaluate passes without critical errors
[ ] hepsw build successfully builds the package
[ ] All dependencies are specified correctly
[ ] Checksums are verified
[ ] Source URL is accessible and stable
[ ] Recipe steps are well-documented
[ ] Commit message is descriptive

4.3. Reporting Issues¶

4.3.1. Bug Reports¶

When reporting bugs, please include:

Description: Clear description of the issue

Steps to Reproduce:

hepsw fetch package-name
hepsw build package-name --with option
# Error occurs here

Expected Behavior: What you expected to happen
Actual Behavior: What actually happened
Environment:
- OS and version (e.g., Ubuntu 22.04, macOS 13.2)
- HepSW version: hepsw --version
- Compiler versions: gcc --version, cmake --version
Build Log: Attach or link to the relevant log file from ~/.hepsw/logs/
Manifest: If the issue is with a specific package, include the manifest

4.3.2. Feature Requests¶

When requesting features, please include:

Use Case: Describe the problem you’re trying to solve
Proposed Solution: How you envision the feature working
Alternatives: Other solutions you’ve considered
Examples: Similar features in other tools (if applicable)

4.4. Code Contributions¶

4.4.1. Setting Up Development Environment¶

# Clone the repository
git clone https://github.com/thisismeamir/hepsw.git
cd hepsw

# Create a virtual environment (if Python-based)
python3 -m venv venv
source venv/bin/activate

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

4.4.2. Development Guidelines¶

Code Style: Follow the existing code style and conventions
Testing: Add tests for new features or bug fixes
Documentation: Update documentation for user-facing changes
Commits: Write clear, descriptive commit messages
Branches: Create feature branches from main or develop

4.4.3. Commit Message Format¶

type: brief description (50 chars or less)

More detailed explanation if needed. Wrap at 72 characters.
Explain what and why, not how.

Fixes #123

Types: feat, fix, docs, test, refactor, style, chore

4.4.4. Pull Request Process¶

Update documentation for any user-facing changes
Add tests for new functionality
Ensure all tests pass
Update CHANGELOG.md if applicable
Request review from maintainers
Address review feedback
Once approved, a maintainer will merge your PR

4.5. Community Guidelines¶

4.5.1. Code of Conduct¶

Be respectful and inclusive
Welcome newcomers and help them get started
Provide constructive feedback
Focus on what’s best for the community
Show empathy towards other community members

4.5.2. Communication Channels¶

GitHub Issues: Bug reports, feature requests, and discussions
GitHub Discussions: General questions and community discussions
Mailing List: [To be announced]
Slack/Discord: [To be announced]

4.6. Recognition¶

Contributors are recognized in:

CONTRIBUTORS.md file
Release notes for significant contributions
Package manifest author field for new packages

4.7. Questions?¶

If you have questions about contributing:

Check existing documentation
Search existing issues and discussions
Open a new discussion on GitHub
Contact maintainers: [contact information]

4.8. Resources¶

Thank you for contributing to HepSW!