Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
82 lines (62 loc) · 2.69 KB

CONTRIBUTING.md

File metadata and controls

82 lines (62 loc) · 2.69 KB
Raw

Contributing to Osgiliath

Thank you for your interest in Osgiliath — the formal Haskell backbone for Arthedain's Hyperdimensional Computing engine.

Code of Conduct

We are committed to fostering an open and welcoming environment. All contributors must adhere to our code of conduct: be respectful, constructive, and inclusive.

How to Contribute

Reporting Issues

  • Bug reports: Open a GitHub issue with a minimal reproduction, expected vs. actual behaviour, and your GHC/cabal version.
  • Feature requests: Describe the use case, why it matters for HDC, and how it connects to Arthedain's Python library.
  • Documentation: Typos, missing haddock, unclear explanations — all welcome.

Pull Requests

  1. Fork the repository and create a feature branch from main.
  2. Write tests for any new functionality. We use:
    • tasty + tasty-hunit for unit tests
    • tasty-quickcheck for property-based tests
  3. Ensure all tests pass: cabal test all
  4. Run hlint and address warnings: hlint src/ tests/
  5. Update haddock documentation for any public API changes.
  6. Open a PR with a clear description of the change and its motivation.

Development Setup

# Install GHC and cabal via ghcup
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh

# Clone and build
git clone https://github.com/Enotrium/Osgiliath.git
cd Osgiliath
cabal build all

# Run tests
cabal test all

Project Structure

Osgiliath/
├── clash-hdc/          # Type-Safe Hardware HDC Generator (Clash)
├── hdc-theory/         # Category-Theoretic Formal Foundation
├── hdc-compiler/       # Verified Multi-Backend HDC DSL
├── hdc-quickcheck/     # Formal Property Testing Framework
└── cabal.project       # Monorepo build file

Coding Standards

  • Language: Haskell 2010 with GHC 9.6+ extensions (DataKinds, GADTs, TypeFamilies, etc.)
  • Style: Follow the style of existing modules. Use explicit imports.
  • Documentation: Every module must have a haddock header. Public functions must have type signatures and documentation.
  • Tests: Every package has a tests/Test.hs test suite. Add new properties to the appropriate package.
  • Safety: Use -Wall -Wincomplete-patterns flags. Avoid partial functions. Prefer Maybe/Either over exceptions.

Package Dependencies

  • hdc-theory has no internal dependencies (foundation layer)
  • hdc-compiler depends on hdc-theory
  • hdc-quickcheck depends on hdc-theory
  • clash-hdc is standalone (Clash-specific)

License

By contributing, you agree that your contributions will be licensed under the BSD 3-Clause License (same as the rest of the project).