Skip to content

Contributing to SCADview

Thanks for your interest in contributing to SCADview!
All contributions are made via pull requests (PRs) from a fork to ensure a clean, reviewable history.

Requirements:

  • Python
  • uv
  • make

TL;DR (Quick Start)

issue → fork → branch (conventional) → change → preflight → commit (conventional) → push → PR
  • Every PR must resolve an issue.
  • Branch names must be conventional with issue number after type/.
  • Follow code style and standards.
  • PRs will be squash merged by a maintainer.
  • Clear commit messages matter.
  • You contribute to conform with the Apache License, Version 2.0.

Contribution Workflow

0. Start With an Issue (Required)

Every pull request must resolve an issue.

  • If an issue already exists, reference it in your PR
  • If no issue exists, create one first with:
  • A clear problem statement.
  • Expected behavior or outcome.
  • Relevant context or constraints.

Small fixes and refactors still require an issue (they may be brief).

1. Fork the Repository

Fork the scadview repository to your own GitHub account using the Fork button.

2. Clone Your Fork

git clone https://github.com/<your-username>/scadview.git
cd scadview

Optional but recommended:

git remote add upstream https://github.com/<original-org-or-user>/scadview.git

This allows you to keep your fork in sync with the main project.

3. Create a Conventional Branch

Do not work directly on main.

Branch names must follow the Conventional Branch specification.

Format:

<type>/<issue-no>-<short-description>

Branch Name Cheat Sheet (short forms)

Type Purpose
feat/ New features
fix/ Bug fixes
hotfix/ Urgent fixes
chore/ Maintenance or non-feature work
release/ Release preparation (maintainers only)

Examples:

  • feat/123-linear-extrude
  • fix/124-mesh-bounds
  • hotfix/125-crash-on-empty-mesh
  • chore/126-update-deps

4. Set Up the Development Environment

This project uses make for commmon tasks.

Window Development: Use Git Bash (included with Git for Windows) for these commands.

  • Most of the make commands require that you run make shell first.
  • To get a list of available commands: 
    make help
  • To get into the shell: 
    make shell

  • This will create a virtual python environment if it does not already exist.

  • To run:

make run

5. Make Your Changes

  • Keep changes focused and scoped to the issue
  • Follow coding standards, as noted below.
  • Follow existing code style and patterns
  • Add or update tests where appropriate
  • Update documentation if public behavior or APIs change

6. Commit Your Changes

This project uses Conventional Commits.

Although PRs are squash merged, commit messages still matter:

  • Maintainers curate the final squash commit message
  • Clear, well-structured commit messages make this easier
  • Well-formed Conventional Commits improve changelogs and release notes

Preferred format:

feat: add linear extrude support
fix: handle empty mesh input

Breaking changes must follow Conventional Commit rules.

The commit types supported in this repo are:

Commit type Example Version impact
build: Build changes Patch
fix: Bug fixes Patch
feat: New user-visible functionality Minor
feat!: or BREAKING CHANGE: Breaking API changes Major
docs: Documentation only Patch
chore: Tooling, CI, maintenance Patch
perf: Performance optimization Patch
refactor: Internal changes Patch
revert: Revert a change Patch?
test: Tests only Patch
ci: GitHub Actions / CI Patch

7. Run Preflight Checks

Before submitting your PR, ensure your changes pass all local checks:

  • Formatting
  • Linting
  • Type checks (if applicable)
  • Tests

If a make preflight, script, or equivalent workflow exists, it must pass before opening a PR. CI failures will block merging.

8. Push to Your Fork

git push origin <your-branch-name>

9. Open a Pull Request

Open a PR from your fork to the main branch of the upstream repository.

  • Fill out the PR template completely
  • Reference the issue the PR resolves:
Resolves: #123
  • Clearly explain:
  • What the change does
  • How it resolves the issue
  • Any trade-offs or follow-up work

Contributor License Notice

By submitting a contribution (code, documentation, or other content) to this repository, you agree that:

  • Your contribution is provided under the Apache License, Version 2.0, and may be distributed, modified, and sublicensed under those same terms.
  • You have the right to submit the work (it is your original creation, or you have sufficient rights to include it).
  • You grant Neil Lamoureux and all users of SCADview a perpetual, worldwide, non-exclusive, royalty-free license to use, modify, and distribute your contribution under the project’s license.

This ensures the project remains open and legally consistent for all contributors.

Code Style and Standards

  • Follow the Google Python Style Guide except:
    • Use ruff instead of pylint for linting.
    • You may import classes, types, etc.
    • Line length limited per ruff
    • Sort imports per ruff
    • Formatting per ruff
    • License boilerplate is not required in every file.
    • Files should end with an empty blank line.
  • Follow existing code patterns and structure where possible.
  • Prefer keeping functions and methods short.
  • Comment where necessary, but keep to a minimum.
    Consider better naming, or extracting a method to make the intent of the code obvious.
  • Use type hints for all methods / functions (code in tests and examples are exceptions)
  • Use docstrings for public methods / functions in src/scadview/api/.
  • Keep dependencies minimal and cross-platform.
  • Write clear, descriptive commit messages.
  • Where possible, add or update tests for new functionality.
  • For scripts, write for bash where possible and follow the Google Shell Style Guide

Communication

If you’re planning a large feature or significant refactor, please open an issue first to discuss your approach before investing time in a PR.

Thank you for helping improve SCADview!