Contribution Guide#

This guide provides information for developers who want to contribute to SACRO Viewer, set up a development environment, or understand the codebase structure.

Getting Started#

System Requirements#

Required Software:

Python 3.10 or later
Node.js v20 or later
just task runner
Git

Platform-Specific Requirements:

Windows:

Visual Studio Community with C++ Desktop Development tools
Git Bash (recommended terminal)
Windows Terminal (recommended)

Linux:

Build essentials (gcc, make, etc.)
Development headers for Python

macOS:

Xcode Command Line Tools
Homebrew (recommended package manager)

Setting Up Development Environment#

Clone and Setup#

# Clone the repository
git clone https://github.com/AI-SDC/SACRO-Viewer.git
cd SACRO-Viewer

# Install Python dependencies
just install

# Install Node.js dependencies
npm install

# Generate test data
just test-outputs

Running in Development Mode#

Start the Django Development Server:

just run

This starts the web application at http://127.0.0.1:8000 with hot-reload enabled.

Start the Asset Development Server (Optional):

For frontend development with hot-reload:

# In a separate terminal
export DJANGO_VITE_DEV_MODE=true
just assets-run

Run the Electron App in Development:

# Start Django server first
just run &

# Set the URL and start Electron
export SACRO_URL=http://127.0.0.1:8000
just sacro-app/run

Project Structure#

sacro-viewer/
├── sacro/                    # Django web application
│   ├── adapters/            # External integrations
│   ├── templates/           # HTML templates
│   ├── staticfiles/         # Compiled static assets
│   ├── models.py           # Data models and ACRO parsing
│   ├── views.py            # HTTP request handlers
│   ├── settings.py         # Django configuration
│   └── urls.py             # URL routing
├── sacro-app/              # Electron application
│   ├── src/                # Electron main process code
│   ├── styles/             # CSS for Electron windows
│   ├── main.js             # Electron entry point
│   └── package.json        # Electron dependencies
├── assets/                 # Frontend source code
│   └── src/                # JavaScript and CSS sources
├── tests/                  # Python unit tests
├── cypress/                # End-to-end tests
├── docs/                   # Documentation source
├── data/                   # Test data generation
├── outputs/                # Sample ACRO outputs
└── justfile                # Task definitions

Core Components#

Django Web Application#

Models (sacro/models.py)

The core data model is ACROOutputs, which handles:

Loading and parsing ACRO metadata files
Validating file structure and content
Generating URLs and checksums
Creating scaffolded metadata for non-ACRO files

Key functions:

# Load ACRO outputs from a directory
outputs = models.load_from_path(path_to_json)

# Get file path for an output
file_path = outputs.get_file_path(output_id, filename)

# Auto-detect ACRO metadata
metadata_path = models.find_acro_metadata(directory_path)

Views (sacro/views.py)

HTTP endpoints that handle:

Directory loading and output display
Secure file content delivery
Review creation and management
Release package generation

Templates (sacro/templates/)

Django templates using:

Base template with common layout
Component-based template organization
Tailwind CSS for styling
Minimal JavaScript for interactivity

Electron Application#

Main Process (sacro-app/main.js)

Handles:

Application lifecycle (startup, shutdown)
Python server management
Native OS integration (menus, dialogs)
Window management

Key Features:

// Start Python server
const server = startServer();

// Create application window
const window = createWindow(serverUrl);

// Handle file dialogs
const directory = await dialog.showOpenDialog({
  properties: ['openDirectory']
});

Frontend Assets#

Build System (Vite)

Modern build tooling providing:

Hot module replacement in development
Asset bundling and optimization
CSS processing with Tailwind
Legacy browser support

JavaScript (assets/src/scripts/)

Vanilla JavaScript for:

File content display and formatting
Review form handling
UI state management
Native file opening integration

Development Workflow#

Making Changes#

Backend Changes (Python):

Modify code in sacro/ directory
Django dev server auto-reloads
Run tests: just test
Check code style: just lint

Frontend Changes (CSS/JS):

Modify files in assets/src/
Vite dev server provides hot-reload
Build assets: just assets-build
Test in Electron: just sacro-app/run

Electron Changes:

Modify files in sacro-app/
Restart Electron app to see changes
Test packaging: just sacro-app/build

Testing#

Unit Tests#

Python unit tests using pytest:

# Run all tests
just test

# Run specific test file
just test tests/test_models.py

# Run with coverage
just test --cov

Test Structure:

tests/test_models.py: ACRO parsing and data models
tests/test_views.py: HTTP endpoints and request handling
tests/test_adapters.py: External integrations
tests/conftest.py: Shared test fixtures

End-to-End Tests#

Cypress tests for full application workflows:

# Interactive test runner
npm run cypress:open

# Headless test execution
npm run cypress:run

Test Scenarios:

Loading directories with ACRO metadata
Reviewing and approving/rejecting outputs
Generating release packages
Error handling and edge cases

Code Quality#

Linting and Formatting#

Python:

# Format code
just format

# Check style
just lint

# Type checking
just check

JavaScript:

# Lint JavaScript
npm run lint

# Format code
npm run format

Pre-commit Hooks:

The project uses pre-commit hooks to ensure code quality:

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files

Building and Packaging#

Development Builds#

Python Application:

# Build PyOxidizer binary
just build

This creates a standalone executable in build/ directory.

Electron Application:

# Build installer packages
just sacro-app/build

Creates platform-specific installers in sacro-app/dist/.

Release Process#

Version Bump: Update version numbers in relevant files
Test Suite: Ensure all tests pass
Build Assets: Generate production frontend assets
Package Application: Create installers for all platforms
GitHub Release: Tag and create release with installers

Automated CI/CD:

GitHub Actions automatically:

Run test suite on all platforms
Build release packages
Create nightly development builds
Deploy documentation updates

Contributing Guidelines#

Code Style#

Python:

Follow PEP 8 style guidelines
Use type hints where appropriate
Write docstrings for public functions
Keep functions focused and testable

JavaScript:

Use modern ES6+ syntax
Prefer const/let over var
Use meaningful variable names
Comment complex logic

General:

Write clear commit messages
Keep changes focused and atomic
Include tests for new functionality
Update documentation as needed

Pull Request Process#

Fork Repository: Create personal fork on GitHub
Create Branch: Use descriptive branch names
Make Changes: Follow coding standards
Add Tests: Ensure adequate test coverage
Update Docs: Document new features
Submit PR: Include clear description of changes

PR Requirements:

All tests must pass
Code coverage should not decrease
Documentation updated if needed
Changes reviewed by maintainers

Debugging#

Development Debugging#