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

> Contribute to Neuro SAN Studio by forking the repo, setting up Python 3.12+, branching, and following Ruff and pylint code standards. Submit your pull request with our guide.

- Repository: [Cognizant AI Lab/neuro-san-studio](https://github.com/cognizant-ai-lab/neuro-san-studio)
- Tags: how-to-guide
- Published: 2026-02-27

---

**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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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:

```bash

# 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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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:

```bash
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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/CONTRIBUTING.md):

- `feature/` for new functionality
- `fix/` for bug fixes
- `docs/` for documentation updates

Example:

```bash
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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/pyproject.toml). The maximum line length is **119 characters**.

Before committing, run:

```bash
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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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:

```bash
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:

```bash
make test

```

This executes the test suite and reports coverage metrics.

### Linting Code and Documentation

Before submission, run the complete validation suite:

```bash

# 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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/.pymarkdownlint.yaml).

## Key Files for Contributors

Understanding the repository structure helps navigate the contribution process:

- **[`CONTRIBUTING.md`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/CONTRIBUTING.md)** – The definitive guide for contributions, coding standards, and PR procedures
- **[`CODE_OF_CONDUCT.md`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/CODE_OF_CONDUCT.md)** – Community behavior expectations
- **[`pyproject.toml`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/pyproject.toml)** – Ruff configuration, test dependencies, and package metadata
- **`Makefile`** – Shortcuts for install, lint, test, and run commands
- **[`.pymarkdownlint.yaml`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/.pymarkdownlint.yaml)** – Markdown linting configuration
- **[`README.md`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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.