Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
112 lines (72 loc) · 4.18 KB

CONTRIBUTING.md

File metadata and controls

112 lines (72 loc) · 4.18 KB

Contributing to IMAS Standard Names

Thank you for your interest in contributing to the IMAS Standard Names project! This document provides guidelines and instructions to help you contribute effectively.

Project Overview

IMAS Standard Names is a grammar library and read-only catalog server for the fusion energy research community. The project defines rules for composing valid standard names and serves the approved catalog through MCP tools.

Name generation is handled by imas-codex. This project focuses on grammar, validation, and catalog serving.

How to Contribute

Areas of Contribution

  • Grammar rules: Propose changes or additions to the naming grammar
  • Validation logic: Improve semantic, structural, or description validation
  • Documentation: Improve grammar reference, guidelines, or architecture docs
  • MCP tools: Enhance the read-only query and reference tools
  • Bug fixes: Fix issues in grammar parsing, catalog building, or validation

Using the IMAS MCP Server for Reference

This repository includes configuration for the Model Context Protocol (MCP) server, which provides schema information and documentation for IMAS data structures.

Note: Using the IMAS MCP server requires a local Docker installation on your system.

VS Code Integration

The repository includes a .vscode/mcp.json configuration file that sets up the necessary MCP servers:

  1. Install Docker on your system if not already installed
  2. Open the project in VS Code with the GitHub Copilot extension enabled
  3. When prompted, enter your GitHub Personal Access Token (Note: this PAT token needs read access to metadata and read/write access to actions, issues, and pull requests)
  4. The MCP servers (IMAS and GitHub) will be accessible to Copilot for providing schema information and documentation

Reporting Issues

If you find a problem or have a suggestion:

  1. Check if the issue already exists in the Issues section.
  2. If not, create a new issue with a clear title and detailed description.
  3. Include relevant examples or error messages.

Submitting Changes

  1. Fork the repository.
  2. Create a new branch with a descriptive name.
  3. Make your changes.
  4. Ensure tests pass with 100% coverage for modified code and update the documentation accordingly.
  5. Submit a pull request with a clear description of the changes.

Development Setup

  1. Fork the repository:

    • Navigate to the repository page.
    • Click the "Fork" button in the top-right corner of the page.

  2. Clone your forked repository:

    git clone https://github.com/<your-username>/imas-standard-names.git
cd imas-standard-names

  3. Set up your development environment:

    uv sync
uv run pre-commit install

  4. Run tests:

    uv run pytest --cov

  5. Create a PR:

    • Make edits.
    • Confirm tests are passing with 100% coverage for updates.
    • Submit your pull request.

Coding Standards

  • Follow PEP 8 style guide for Python code.
  • Include docstrings for all functions, classes, and modules.
  • Write tests for new functionality.
  • Keep commits focused and related to a single issue when possible.
  • Use conventional commit messages (e.g., feat:, fix:, docs:).

Review Process

  1. All pull requests require review by at least one maintainer.
  2. Automated tests must pass.
  3. Update the documentation alongside code changes.
  4. Reviewers may request changes before merging.

Proposing Standard Names

To propose new standard names, use the imas-standard-names-catalog repository. Names are generated by imas-codex and reviewed by domain experts before being merged into the catalog.

License

By contributing to this project, you agree to license your contributions under the project's license.

Questions?

If you have questions about contributing, please open an issue or contact the maintainers.

Thank you for contributing to the IMAS Standard Names project!