Contributing - Shed Skin

Welcome Contributors

Shed Skin is an open source project that thrives on community contributions. Whether you’re fixing bugs, adding features, improving documentation, or extending library support, your contributions are valued and appreciated.

Shed Skin has successfully participated in Google Summer of Code and GHOP. Students are encouraged to apply for yearly programs!

Ways to Contribute

Report Bugs

Found a bug? Please report it!

Check existing issues: Search GitHub Issues to avoid duplicates
Create a new issue: Provide:
- Minimal code example that reproduces the bug
- Shed Skin version (shedskin --version)
- Operating system and version
- Expected vs. actual behavior
- Full error message and traceback
Be responsive: Answer questions from maintainers to help debug

Simplify your test case to the smallest possible code that demonstrates the issue. This helps maintainers fix bugs faster.

Suggest Features

Have ideas for improvements?

Open a GitHub issue with the enhancement label
Describe the feature and its use case
Explain why it would benefit Shed Skin users
Discuss implementation approaches if you have ideas

Contribute Code

Code contributions are especially welcome for:

Bug fixes
Performance improvements
Support for additional Python features
New library module implementations
Test coverage improvements
Build system enhancements

Improve Documentation

Documentation contributions help everyone:

Fix typos and unclear explanations
Add examples and tutorials
Document undocumented features
Improve API documentation
Translate documentation

Add Library Support

One of the most valuable contributions is adding support for more standard library modules. See Adding Library Modules below.

Getting Started

Easy Tasks

New to the project? Start with issues labeled easytask on GitHub. These are beginner-friendly tasks that will help you understand the codebase.

Development Setup

Prerequisites

Python 3.8 or later
Git
C++ compiler (g++, clang, or MSVC)
uv (Python package installer)

Clone the Repository

git clone https://github.com/shedskin/shedskin.git
cd shedskin

Install Development Dependencies

Shed Skin uses uv for dependency management:

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Shed Skin in development mode
uv pip install -e .

# Install development dependencies
uv pip install -e ".[dev]"

Verify Installation

shedskin --version

Project Structure

Key directories and files:

shedskin/
├── shedskin/           # Main package
│   ├── __init__.py     # CLI entry point
│   ├── graph.py        # AST analysis and constraint graph
│   ├── infer.py        # Type inference engine
│   ├── cpp.py          # C++ code generation
│   ├── error.py        # Error reporting
│   ├── config.py       # Global configuration
│   ├── cmake.py        # CMake build integration
│   ├── makefile.py     # Makefile generation
│   └── lib/            # Supported library modules
│       ├── builtin.py  # Builtin types type models
│       ├── random.py   # random module type model
│       └── ...         # Other module type models
├── shedskin/resources/ # C++ header files
│   └── lib/            # C++ implementations
│       ├── builtin.hpp # Builtin types implementation
│       ├── builtin.cpp
│       └── ...         # Other module implementations
├── tests/              # Test suite
│   ├── unit/           # Unit tests
│   └── test_*.py       # Integration tests
├── examples/           # Example programs
└── docs/               # Documentation

Development Workflow

Making Changes

Create a branch for your changes:
```
git checkout -b fix-issue-123
```
Make your changes following the code style
Test your changes (see Testing below)

Commit with clear messages:

git commit -m "Fix type inference for dict comprehensions"

Push your branch:
```
git push origin fix-issue-123
```
Open a Pull Request on GitHub

Code Style

Shed Skin follows Python best practices:

PEP 8: Follow Python style guide
Type hints: Use type annotations (the codebase is gradually being typed)
Docstrings: Document functions and classes
Mypy: The codebase is moving towards mypy strict mode

Running Mypy

Type check your changes:

mypy shedskin/

Core modules already use strict mode. When editing these, ensure no new type errors are introduced.

Testing

Running Tests

Unit Tests

Run Python unit tests with pytest:

# Run all unit tests
pytest tests/unit/

# Run specific test file
pytest tests/unit/test_graph.py

# Run with verbose output
pytest -v tests/unit/

Integration Tests

Run full compilation tests:

cd tests

# Run all tests as executables
shedskin runtests -x

# Run all tests as executables and extensions
shedskin runtests -xe

# Run single test
shedskin runtests --run test_builtin_str

# Run with parallel jobs
shedskin runtests -x --jobs 4

# Run most recently modified test
shedskin runtests -x --modified

Writing Tests

When adding features or fixing bugs, add tests:

Unit Tests

Add to tests/unit/:

# tests/unit/test_myfeature.py
import pytest
from shedskin import config, graph

def test_my_feature():
    gx = config.GlobalInfo()
    # Test your feature
    assert expected == actual

Integration Tests

Add to tests/:

# tests/test_myfeature.py
def test_feature_case1():
    assert 1 + 1 == 2

def test_feature_case2():
    data = [1, 2, 3]
    assert sum(data) == 6

def test_all():
    test_feature_case1()
    test_feature_case2()

if __name__ == '__main__':
    test_all()

Test naming conventions:

File: test_<name>.py
Functions: test_<name>()
Include test_all() that calls all test functions
Must run with python test_myfeature.py and pytest

Keep tests fast. Reduce iteration counts for performance tests - they’re for correctness, not benchmarking.

Test Standards

All tests should:

✅ Run successfully with pytest
✅ Run successfully with python test_file.py
✅ Compile and run correctly with Shed Skin
✅ Use meaningful names that describe what’s being tested
✅ Include assertions to verify correctness
✅ Avoid using global keyword (pytest incompatibility)
✅ Complete quickly (adjust parameters for speed)

Adding Library Modules

Adding support for Python standard library modules is one of the most valuable contributions. Currently, about 30 modules are supported, but many more could be added.

How Library Modules Work

Shed Skin library modules consist of two parts:

Type model (shedskin/lib/modulename.py): Python code that provides type information for inference
C++ implementation (shedskin/resources/lib/modulename.{hpp,cpp}): C++ code that implements the functionality

Adding a Module: Step by Step

1. Create a Type Model

Create shedskin/lib/modulename.py with Python signatures:

# shedskin/lib/modulename.py

def function_name(arg: int) -> str:
    """Type model for function_name."""
    return ""  # Implementation doesn't matter

class ClassName:
    def __init__(self, value: int):
        self.value = value
    
    def method(self) -> int:
        return 0

The type model doesn’t need to be functional - only the signatures matter. Shed Skin uses it only for type inference.

2. Compile the Type Model

Create a test program that uses the module:

# test_module.py
import modulename

result = modulename.function_name(42)
print(result)

Compile it:

shedskin translate test_module

This generates modulename.cpp and modulename.hpp.

3. Implement C++ Code

Edit modulename.cpp and modulename.hpp to implement actual functionality:

// modulename.hpp
#ifndef __MODULENAME_HPP
#define __MODULENAME_HPP

#include "builtin.hpp"

namespace __modulename__ {

str *function_name(int arg);

} // namespace __modulename__
#endif

// modulename.cpp
#include "modulename.hpp"

namespace __modulename__ {

str *function_name(int arg) {
    // Actual implementation
    return new str("result");
}

} // namespace __modulename__

4. Move to Library Directory

Move the files to make them part of Shed Skin:

mv modulename.cpp shedskin/resources/lib/
mv modulename.hpp shedskin/resources/lib/

Now any Shed Skin program can import modulename.

5. Add Tests

Create tests/test_lib_modulename.py:

import modulename

def test_function():
    result = modulename.function_name(42)
    assert result == "expected"

def test_all():
    test_function()

if __name__ == '__main__':
    test_all()

Test it:

cd tests
shedskin runtests --run test_lib_modulename

Tips for Library Modules

Start small: Begin with a few key functions
Study existing modules: Look at lib/random.py, lib/re.py as examples
Use Shed Skin types: See builtin.hpp for available C++ classes
Handle memory correctly: Use the Boehm GC (new without delete)
Test thoroughly: Ensure compiled output matches Python behavior
Document limitations: Note any partial implementations

Pull Request Process

Before Submitting

✅ Tests pass locally
✅ Code follows style guidelines
✅ Commits have clear messages
✅ No unrelated changes included
✅ Documentation updated if needed

Submitting PR

Open Pull Request on GitHub
Fill out PR template with:
- Description of changes
- Related issue numbers
- Testing performed
- Breaking changes (if any)
Respond to feedback from maintainers
Update PR based on review comments

After Submission

CI tests will run automatically
Maintainers will review your code
Address any requested changes
Once approved, your PR will be merged

Don’t be discouraged if changes are requested - code review is a normal part of the process and helps maintain code quality.

Community

Communication

GitHub Issues: Bug reports, feature requests, questions
Pull Requests: Code review and discussion
Discussions: General questions and community interaction

Code of Conduct

Be respectful and professional:

Welcome newcomers
Be patient with questions
Provide constructive feedback
Focus on the code, not the person
Respect different opinions and approaches

Recognition

All contributors are acknowledged in the README. Your contributions, no matter how small, are valued and appreciated. Thank you for contributing to Shed Skin!

Contributors

Shed Skin has been developed by many contributors over the years. Current active maintainers and major contributors include:

Mark Dufour - Original author and maintainer
Many others - See the full list in the README

Your name could be here too!

​Welcome Contributors

​Ways to Contribute

​Report Bugs

​Suggest Features

​Contribute Code

​Improve Documentation

​Add Library Support

​Getting Started

​Easy Tasks

​Development Setup

​Prerequisites

​Clone the Repository

​Install Development Dependencies

​Verify Installation

​Project Structure

​Development Workflow

​Making Changes

​Code Style

​Running Mypy

​Testing

​Running Tests

​Unit Tests

​Integration Tests

​Writing Tests

​Unit Tests

​Integration Tests

​Test Standards

​Adding Library Modules

​How Library Modules Work

​Adding a Module: Step by Step

​1. Create a Type Model

​2. Compile the Type Model

​3. Implement C++ Code

​4. Move to Library Directory

​5. Add Tests

​Tips for Library Modules

​Pull Request Process

​Before Submitting

​Submitting PR

​After Submission

​Community

​Communication

​Code of Conduct

​Recognition

​Contributors

Welcome Contributors

Ways to Contribute

Report Bugs

Suggest Features

Contribute Code

Improve Documentation

Add Library Support

Getting Started

Easy Tasks

Development Setup

Prerequisites

Clone the Repository

Install Development Dependencies

Verify Installation

Project Structure

Development Workflow

Making Changes

Code Style

Running Mypy

Testing

Running Tests

Unit Tests

Integration Tests

Writing Tests

Unit Tests

Integration Tests

Test Standards

Adding Library Modules

How Library Modules Work

Adding a Module: Step by Step

1. Create a Type Model

2. Compile the Type Model

3. Implement C++ Code

4. Move to Library Directory

5. Add Tests

Tips for Library Modules

Pull Request Process

Before Submitting

Submitting PR

After Submission

Community

Communication

Code of Conduct

Recognition

Contributors