biobox/CONTRIBUTING.md

Contributing Guidelines

We encourage contributions from the community! This guide will help you get started with creating new components for the biobox repository.

Quick overview: Fork → Develop → Test → Submit PR

Quick Start

Essential Config Template

name: your_tool
namespace: category
description: Brief description of what the tool does
keywords: [tag1, tag2]
links:
  homepage: https://tool-homepage.com
  documentation: https://tool-docs.com
  repository: https://github.com/user/repo
references:
  doi: 10.1000/journal.12345
license: MIT/Apache-2.0/GPL-3.0
requirements:
  commands: [your-tool, dependency-tool]
authors:
  - __merge__: /src/_authors/your_name.yaml
    roles: [author, maintainer]
argument_groups:
  - name: Inputs
    arguments: [...]
  - name: Outputs  
    arguments: [...]
resources:
  - type: bash_script
    path: script.sh
test_resources:
  - type: bash_script
    path: test.sh
engines:
  - type: docker
    image: quay.io/biocontainers/tool:version--build_string
    setup:
      - type: docker
        run:
          - tool --version 2>&1 | head -1 | sed 's/.*version /tool: /' > /var/software_versions.txt
runners:
  - type: executable
  - type: nextflow

Essential Commands

# Create component structure
mkdir -p src/namespace/tool_name
touch src/namespace/tool_name/{script.sh,test.sh,config.vsh.yaml}

# Generate help file
docker run container tool --help > src/namespace/tool_name/help.txt

# Test your component
viash test src/namespace/tool_name/config.vsh.yaml

# Build for testing
viash build src/namespace/tool_name/config.vsh.yaml --setup cachedbuild

Key Best Practices

• Follow modern standards: Use current coding patterns and component structure
• Ensure reproducibility: Pin versions and document dependencies clearly
• Generate test data: Create self-contained tests that don't rely on external files
• Write clean code: Use consistent naming and clear, maintainable scripts

For detailed implementation guidelines, check out our development guides:

Development Guides

🔧 Component Development Guide

How to create components: config templates, metadata, arguments, containers, help files, and Docker setup.

📝 Script Development Guide

Writing good scripts: array-based commands, error handling, conditional parameters, boolean flags, and parameter patterns.

✅ Testing Guide

Testing your components: self-contained tests, generating test data, output validation, and testing multiple scenarios.

🐳 Docker Guide

Working with containers: choosing biocontainers, version pinning, detecting software versions, and container best practices.

Contribution Process

Submitting Your Component

1. Test thoroughly: Ensure your component passes all tests

   viash test src/namespace/tool_name/config.vsh.yaml
   

2. Add changelog entry: Document your changes in CHANGELOG.md under the "Unreleased" section

3. Review your changes: Check your code for:

   • Consistent naming and coding conventions
   • Clear, maintainable code structure
   • Proper error handling
   • Robust edge case management
   • Complete documentation and helpful comments

4. Create a pull request: Submit your changes.

• Include a clear description of the changes you've made
• Link to any relevant issues or discussions
• Review the changes critically before submitting the PR

Review Process

• All contributions go through code review
• Components must pass automated tests
• Docker containers must be properly versioned
• Documentation must be complete and accurate

Getting Help

Resources

• Viash Documentation
• GitHub Discussions
• Issue Tracker

Common Questions

Q: How do I find the right Docker container?
A: Search for "biocontainer [tool_name]" or check quay.io/biocontainers

Q: My component fails to build. What should I check?
A: Verify the Docker image exists, check syntax in config.vsh.yaml, and ensure all required commands are available

Q: How do I handle tools with complex argument patterns?
A: Check existing similar components for patterns, or ask in GitHub Discussions

Q: Can I create custom Docker containers?
A: Yes, but biocontainers are preferred when available. See the Docker Guide for details.

---

Happy contributing!