Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
199 lines (138 loc) · 5.42 KB

CONTRIBUTING.md

File metadata and controls

199 lines (138 loc) · 5.42 KB
Raw

Contributing to Dockyard

Thank you for your interest in contributing to Dockyard! This document helps you get started.

Table of Contents

Code of Conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to code-of-conduct@stacklok.dev.

Reporting Security Vulnerabilities

If you think you have found a security vulnerability in Dockyard, please DO NOT disclose it publicly until we've had a chance to fix it. Please don't report security vulnerabilities using GitHub issues; instead, follow the process in SECURITY.MD.

Ways to Contribute

Add an MCP Server

The most common contribution is adding a new MCP server to Dockyard. See Adding an MCP Server below.

Add an Agent Skill

You can also vendor an agent skill (your own, or a third-party one) as a Dockyard skill artifact. See Adding an Agent Skill below.

Report Bugs

Use GitHub Issues to report bugs. Please include:

  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Container image name and version (if applicable)

Suggest Enhancements

We welcome feature suggestions! Open an issue describing:

  • The problem you're trying to solve
  • Your proposed solution
  • Any alternatives you've considered

Improve Documentation

Documentation improvements are always welcome. See the docs/ directory.

Adding an MCP Server

To add your MCP server to Dockyard:

  1. Create a directory: {protocol}/{server-name}/
  2. Add a spec.yaml configuration file
  3. Submit a pull request

Full guide: Adding MCP Servers

Quick example:

metadata:
  name: my-server
  description: "What my server does"
  protocol: npx

spec:
  package: "@my-org/mcp-server"
  version: "1.0.0"

Adding an Agent Skill

To add an agent skill to Dockyard:

  1. Create a directory: skills/{skill-name}/
  2. Add a spec.yaml configuration file pointing at the skill's source repo, pinned commit, and path
  3. Run task validate-skill -- skills/{skill-name} and task scan-skill -- skills/{skill-name} locally, triaging any security findings into the allowlist
  4. Submit a pull request

Full guide: Adding Skills

Quick example:

metadata:
  name: my-skill
  description: "What my skill does"

spec:
  repository: "https://github.com/my-org/my-skill-repo"
  ref: "abc1234..."  # pinned commit SHA
  path: "skills/my-skill"  # omit if SKILL.md is at repo root
  version: "0.1.0"

Development Setup

Prerequisites

  • Go 1.21+
  • Docker or Podman
  • Task (optional, for convenience)

Build the CLI

go build -o build/dockhand ./cmd/dockhand

Run Tests

go test ./...

Generate a Dockerfile

./build/dockhand build -c npx/context7/spec.yaml

Verify Provenance

./build/dockhand verify-provenance -c npx/context7/spec.yaml -v

Pull Request Process

  1. Fork and clone the repository
  2. Create a branch for your changes
  3. Make your changes with clear, focused commits
  4. Test locally:
    • If adding an MCP server: 
      task build -- {protocol}/{server-name}
task scan -- {protocol}/{server-name}
    • If adding an agent skill: 
      task validate-skill -- skills/{skill-name}
task scan-skill -- skills/{skill-name}
  5. Submit a PR with a clear description

PR Requirements

  • All commits must include a Signed-off-by trailer (DCO)
  • CI checks must pass (security scan, build, etc.)
  • One approval from a maintainer is required

For MCP Server PRs

Include in your PR description:

  • What the MCP server does
  • Link to the package registry (npm/PyPI)
  • Link to the source repository

For Agent Skill PRs

Include in your PR description:

  • What the skill does
  • Link to the source repository and the pinned commit
  • The license permitting redistribution and where it is declared upstream
  • A brief note on any security.allowed_issues entries you added and why

Commit Message Guidelines

Follow Chris Beams' guidelines:

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Use the body to explain what and why vs. how

Example:

Add context7 MCP server

Add packaging for context7 v1.0.14 from Upstash.
This server provides vector search and context management.

Package: https://www.npmjs.com/package/@upstash/context7-mcp
Repository: https://github.com/upstash/context7-mcp

Signed-off-by: Your Name <your.email@example.com>

Questions?