Contributing Guide

How to contribute to the VHDL Digital Design Samples project.

Getting Started

  1. Fork the repository on GitHub

  2. Clone your fork locally

  3. Set up the development environment

  4. Create a feature branch for your changes

  5. Make your changes following the coding standards

  6. Test your changes thoroughly

  7. Submit a pull request

Development Setup

# Clone your fork
git clone https://github.com/shishir-dey/vhdl-samples.git
cd vhdl-samples

# Install GHDL
make install  # macOS
# or sudo apt-get install ghdl  # Ubuntu

# Install documentation dependencies (optional)
make docs-install

# Run tests to verify setup
make test

Coding Standards

VHDL Code Style:

  • Use lowercase with underscores for entity names

  • Use PascalCase for architecture names

  • Follow consistent indentation (2 spaces)

  • Include comprehensive comments

File Organization:

  • Place source files in appropriate src/ subdirectories

  • Create corresponding test files in test/ subdirectories

  • Follow existing naming conventions

Testing Requirements:

  • Every new component must have a testbench

  • Tests should be comprehensive and self-checking

  • Use assertions for automatic verification

Submitting Changes

  1. Create a feature branch: git checkout -b feature/new-component

  2. Make your changes with clear, descriptive commits

  3. Run tests: make test to ensure nothing breaks

  4. Update documentation if needed

  5. Push to your fork: git push origin feature/new-component

  6. Open a pull request with a clear description

Pull Request Guidelines

Good Pull Requests:

  • Have a clear, descriptive title

  • Include a detailed description of changes

  • Reference any related issues

  • Include tests for new functionality

  • Update documentation when needed

  • Pass all existing tests

Review Process:

  • Maintainers will review your PR

  • Address any feedback promptly

  • Be patient - reviews may take time

  • Keep your PR up to date with the main branch

Types of Contributions

New Components:

  • Logic gates and basic circuits

  • Combinational logic designs

  • Sequential logic implementations

  • Complex digital systems

Documentation:

  • Component documentation

  • Tutorial improvements

  • API documentation

  • Example code

Testing:

  • New testbenches for existing components

  • Improved test coverage

  • Performance benchmarks

  • CI/CD improvements

Bug Fixes:

  • VHDL syntax errors

  • Simulation issues

  • Documentation corrections

  • Build system improvements

Code of Conduct

Be respectful and constructive in all interactions. This is an educational project aimed at helping people learn VHDL.