How to Collaborate

JuSPICE is hosted on the Forschungszentrum Jülich GmbH GitLab instance:

You need a jugit account to open issues or submit merge requests. The sign-in page (jugit.fz-juelich.de/users/sign_in) offers two federated login options — how to get access depends on your affiliation:

  • FZJ staff and internal collaborators: sign in with your FZJ account via Shibboleth. If your account is not yet enabled for jugit, request access through the FZJ IT services / JSC helpdesk.

  • External guests (non-FZJ): sign in via Helmholtz AAI, which accepts guest identities (e.g. via ORCID or other affiliated identity providers) and does not require sponsorship by an FZJ staff member. Once you have signed in once, a project maintainer can add you as a member of the JuSPICE project if needed — see Contact.

All contributions — bug reports, feature requests, documentation improvements, new notebooks, or module enhancements — are welcome via the issue tracker and merge requests on that platform.

Reporting Issues

  1. Navigate to the repository at the URL above.

  2. In the left sidebar, go to Plan → Work items.

  3. Click New item.

  4. In the Project dropdown, choose juSPICE; in the Type dropdown, choose Issue.

  5. Choose an appropriate title, and in the Description text box explain the issue, the contribution you have made, or any suggestion or bug clearly:

    • For bugs: include the Python version, JuSPICE version, minimal reproducible example, and the full traceback.

    • For feature requests: explain the use case and, where possible, sketch the expected API.

  6. Click Create issue.

Submitting a Merge Request

JuSPICE follows the standard GitLab fork-and-merge-request workflow.

Step 1 — Fork the repository

On the jugit repository page click Fork (top-right). GitLab creates a personal copy of the repository under your jugit account.

Step 2 — Clone your fork

git clone https://jugit.fz-juelich.de/<your-username>/juspice.git
cd juspice

Add the upstream remote so you can keep your fork up to date:

git remote add upstream https://jugit.fz-juelich.de/iet-1/juspice.git

Step 3 — Create a feature branch

Always branch off from main (never commit directly to it):

git fetch upstream
git checkout -b feature/my-descriptive-name upstream/main

Step 4 — Make your changes

  • Follow the coding conventions in Developer Guide.

  • Keep changes focused: one logical change per merge request.

  • If you add a module feature, update or add the corresponding notebook under notebooks/.

  • Run the same checks Continuous Integration (CI) runs, before pushing. The development tools (pytest, ruff, black, mypy) are part of JuSPICE’s core install, so they’re already available once uv pip install -e . has been run once (see Installation):

    ruff check juspice tests notebooks
black --check juspice tests notebooks
pytest tests/

Step 5 — Commit and push

git add <changed-files>
git commit -m "Short imperative description of the change"
git push origin feature/my-descriptive-name

Step 6 — Open a Merge Request

  1. Go to your fork on jugit.fz-juelich.de.

  2. GitLab will display a banner: “You pushed a branch — create a merge request”. Click it, or navigate to Merge Requests → New merge request.

  3. Set:

    • Source branch: your feature branch in your fork

    • Target branch: main in iet-1/juspice

  4. Fill in the MR description:

    • Summarise what changed and why.

    • Reference related issues with Closes #<issue-number> if applicable.

    • List any manual testing steps or screenshots for UI/notebook changes.

  5. Submit the MR. The maintainer will review it, leave comments, and either request changes or approve and merge.

Step 7 — Address review feedback

Push additional commits to your feature branch; they appear in the MR automatically. Once all discussions are resolved and CI passes, the maintainer merges the request.

Contribution Guidelines

  • Keep workflows reproducible: document assumptions, parameters, and data provenance.

  • Follow the developer practices described in Developer Guide.

  • Do not add large binary files (images, model weights) to the repository; reference them via download scripts or external storage instead.