Contributing

How to contribute to the Notations project

Thank you for your interest in contributing to the Notations project. This guide will help you get started with contributing code, documentation, or examples.

Getting Started

The Notations project is open source and welcomes contributions. The codebase is organized into several packages:

  • notations - Core library (parser, models, layout)
  • notations-web - Browser components for rendering
  • docs - Documentation site (this site)

Development Setup

Clone the repository and install dependencies:

git clone https://github.com/panyam/notation.git
cd notation
pnpm install

Build the core library:

cd notations
pnpm build
pnpm test

Making Changes

  1. Create a new branch for your feature or fix
  2. Make your changes with clear commit messages
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Update documentation as needed
  6. Submit a pull request

Code Style

The project uses TypeScript with ESLint and Prettier for code formatting:

pnpm lint
pnpm lintfix

Testing

All new features should include tests. Run the test suite:

pnpm test

Tests are located in the src/tests/ directory.

Documentation

Documentation improvements are always welcome. The docs site is built with s3gen:

cd docs
go run . serve

Documentation files are in docs/content/ and use HTML with frontmatter.

Areas for Contribution

  • Parser improvements - Better error messages, new syntax features
  • Layout algorithms - Improved rendering and spacing
  • Gamaka support - Additional embellishment types
  • Documentation - Tutorials, examples, cookbook recipes
  • Web components - Interactive features, editing capabilities
  • Examples - Real compositions notated with the library

Reporting Issues

If you find a bug or have a feature request, please open an issue on GitHub with:

  • A clear description of the problem or feature
  • Steps to reproduce (for bugs)
  • Expected vs actual behavior
  • Example notation source (if applicable)

Community

Join the discussion and get help:

  • GitHub Issues - Bug reports and feature requests
  • GitHub Discussions - Questions and general discussion

License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project.

See Also