How to Contribute to Neuro SAN Studio: A Complete Guide to Code Standards and Pull Requests

To contribute to Neuro SAN Studio, fork the repository, set up a Python 3.12+ virtual environment using the Makefile, create a feature branch, write code that passes Ruff formatting and pylint checks, and submit a pull request that follows the commit message template.

Contributing to Neuro SAN Studio requires following a structured workflow defined in the repository's CONTRIBUTING.md file. This guide walks through the complete process—from environment setup to submitting a pull request—while adhering to the strict code standards enforced by the maintainers.

Prerequisites and Development Environment Setup

Before writing code, you must configure a local development environment that matches the project's Python version and tooling requirements.

Python Version and Virtual Environment

Neuro SAN Studio targets Python 3.12 and 3.13. The project uses a virtual environment to isolate dependencies. While you can create one manually, the provided Makefile automates this process.

Installing Dependencies with the Makefile

The repository includes a Makefile that standardizes common tasks. To set up your environment:

# Clone your fork

git clone https://github.com/your-username/neuro-san-studio.git
cd neuro-san-studio

# Install dependencies and create virtual environment

make install

# Activate the virtual environment

source venv/bin/activate  # macOS/Linux

# .\venv\Scripts\activate.bat  # Windows

The make install command handles dependency installation as specified in pyproject.toml.

Understanding the Contribution Workflow

The contribution process follows a standard GitHub flow with specific naming conventions and quality gates.

Forking and Cloning the Repository

Contributions must be made through personal forks. After forking the cognizant-ai-lab/neuro-san-studio repository, clone it locally and add the upstream remote to sync with the main branch:

git remote add upstream https://github.com/cognizant-ai-lab/neuro-san-studio.git

Branch Naming Conventions

Create descriptive branches using the prefixes defined in CONTRIBUTING.md:

• feature/ for new functionality
• fix/ for bug fixes
• docs/ for documentation updates

Example:

git checkout -b feature/add-openai-video-tool

The Pull Request Process

When ready to submit:

1. Push your branch to your fork: git push origin feature/your-feature
2. Open a Pull Request via the GitHub UI
3. Fill out the PR template completely, including:
   • Description of changes
   • Motivation for the change
   • Related issue numbers
   • Testing steps performed

The maintainers will review your code against the standards defined in CONTRIBUTING.md before merging.

Neuro SAN Studio Code Standards

All code must pass automated linting and follow the Google Python Style Guide conventions specified in the repository.

Line Length and Formatting with Ruff

The project uses Ruff v0.11.12 for both formatting and linting, configured in pyproject.toml. The maximum line length is 119 characters.

Before committing, run:

make lint

This executes Ruff to check formatting and code quality rules.

Naming Conventions (Google Python Style Guide)

Follow these specific naming patterns as defined in CONTRIBUTING.md:

• Functions and variables: snake_case
• Classes: PascalCase
• Constants: UPPER_CASE

Documentation Requirements

Every public function, class, and module must include a descriptive docstring. Complex logic requires inline comments explaining the "why" rather than the "what."

Logging vs Print Statements

The codebase requires using the logging module instead of print() statements for output. This ensures consistent log levels and output formatting across the application.

Static Analysis with Pylint

In addition to Ruff, the project runs pylint for deeper static analysis. Run it via:

make lint

The CI pipeline enforces both Ruff and pylint compliance, so local verification is essential before submitting a PR.

Testing and Validation

Quality assurance requires both unit tests and documentation linting.

Running Tests Locally

The test suite uses the standard tests/ directory structure, mirroring the source layout. Run tests with coverage using:

make test

This executes the test suite and reports coverage metrics.

Linting Code and Documentation

Before submission, run the complete validation suite:

# Code linting (Ruff + pylint)

make lint

# Test code linting

make lint-tests

# Markdown linting (docs and README)

# Configuration is in .pymarkdownlint.yaml

The repository uses pymarkdown for documentation quality, configured in .pymarkdownlint.yaml.

Key Files for Contributors

Understanding the repository structure helps navigate the contribution process:

• CONTRIBUTING.md – The definitive guide for contributions, coding standards, and PR procedures
• CODE_OF_CONDUCT.md – Community behavior expectations
• pyproject.toml – Ruff configuration, test dependencies, and package metadata
• Makefile – Shortcuts for install, lint, test, and run commands
• .pymarkdownlint.yaml – Markdown linting configuration
• README.md – Project overview and quick-start instructions
• docs/ – User guides, tutorials, and developer documentation
• tests/ – Unit and integration tests (mirror source structure)
• coded_tools/ – Custom Python tools for agent invocation

Summary

• Fork and clone the cognizant-ai-lab/neuro-san-studio repository, then run make install to set up your Python 3.12+ environment.
• Create descriptive branches using feature/, fix/, or docs/ prefixes before writing code.
• Follow code standards: maximum 119-character lines, Ruff v0.11.12 formatting, Google Python Style Guide naming (snake_case, PascalCase), and mandatory docstrings.
• Validate locally using make lint (Ruff + pylint), make lint-tests, and make test before submitting.
• Submit PRs that reference issue numbers, fill the template completely, and pass CI checks.

Frequently Asked Questions

What Python versions are supported for contributing to Neuro SAN Studio?

The project officially supports Python 3.12 and 3.13. You must use one of these versions in your virtual environment to ensure compatibility with the dependencies and tooling specified in pyproject.toml.

How do I run linting checks before submitting a PR?

Run the command make lint from the repository root. This executes Ruff v0.11.12 for formatting and linting, plus pylint for additional static analysis. Also run make lint-tests to validate your test code and make test to ensure all tests pass.

What should I include in my commit messages?

Follow the template format: #issue-number: Brief description. For example: #123: Add OpenAI video generation coded tool. Include a blank line followed by bullet points describing specific changes, such as implementation details, test coverage, and documentation updates.

Where do I add tests for new features?

Add tests in the tests/ directory, mirroring the structure of the source code you modified. For example, if you add functionality to coded_tools/, create corresponding test files in tests/coded_tools/. The project follows the arrange-act-assert pattern and requires mocking external calls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}