Repository Template

Vision: SDSC Excellence | Always be encouraging

Get in contact

• Slack Channel : #best-practice-ambassadors

Authors:

• Gabriel Nützi
• Cyril Matthey-Doret

Table of Content (click to expand)

• Repository Template
• What Is This?
• Usage
  • Cloning
  • Containerized
• Structure
  • Generic Template
    • Features
    • Toolchain
  • Rust Template
    • Toolchain
  • Go Template
    • Toolchain
  • Python Template - Toolchain

What Is This?

This is a repository template giving you a top-level structure with the following features.

• Git & Git Large File System (LFS) properly setup.
• Nix development shell enabled with direnv and .envrc.
• Formatting with treefmt-nix.
• Githooks (optional) which runs pre-commit checks:
  • Git LFS checks.
  • Format with treefmt-nix.
• Language specific best-practice setup for rust, go and python.
• Devcontainer: not-yet-provided (future, based on Nix dev shell)

Usage

Cloning

Clone this repository to some place of your choice.

Apply the templates with copier using the following:

cd repo && git pull
just create <language> <destination> [args...]

where

• <destination> is the destination folder where you want to place this new repository.

• <language> is one of the following templates:

  • generic: For a generic repository without any language specific needs.
  • python: For python toolchain with uv and other good tooling.
  • rust: For a Rust toolchain with cargo
  • go: For a default Go toolchain.

• [args...] are optional arguments passed to copier. If you want to overwrite by default use -w.

Containerized

TODO: Add this.

Structure

The following describes the content of the top-level directories:

• docs : The top-level folder to any related documentation. The README.md should link into this folder.
• examples : The top-level folder which should contain some examples how to use this software component.
• external : If you really want to use sub-modules (which you generally should avoid for a multitude of reasons), your external stuff should be either placed in here or in src/external if its more related to your source.
• src: The folder where your source code lives.
• tools: The folder for all specific needs:
  • configs: A collection folder for all config related files for certain tools like, e.g. formatters, linters etc.
  • nix: The folder containing all Nix related stuff.
  • ci: Folder containing all CI related tooling/scripts.
  • scripts: Folder containing additional scripts complementing the justfile etc.

Generic Template

• Template Source
• Demo Rendering

Features

• Git & Git LFS properly setup: .gitignore, .gitattributes

• Nix development shell based on devenv auto-enabled with direnv and .envrc.

• Formatting with treefmt-nix and treefmt.nix config.

• Githooks (optional) which runs pre-commit checks:

  • Git LFS checks
  • Format with treefmt-nix.

  [!NOTE] You need to install the Githooks tool yourself if you want to use it and it will work out-of-the-box.

Toolchain

Source

• Command-Runner: just
• Nix Shell: devenv provided Nix shell using toolchain-generic.nix.
• Formatter: Tree format with treefmt-nix and enabled languages

Rust Template

• Template Source
• Demo Rendering

Toolchain

Source

• Toolchain: Rust toolchain on nightly
• Build-Tool: cargo
• LSP: rust-analyzer
• Formatter: rustfmt

Go Template

• Template Source
• Demo Rendering

Toolchain

Source

• Compiler: go at 1.23.X
• Build-Tool: go
• LSP: gopls
• Formatter: gofmt, goimports, golines

Python Template

Template Source

Toolchain

• Source

• Demo Rendering

• Interpreter: python at 3.12

• Build-Tool: uv

• LSP: pyright

• Formatter: ruff

CI Implementations

Github Actions

The following workflows are defined:

• format.yaml: A format workflow which formats the whole repository with treefmt which is configured over Nix. For it to work with cachix (a Nix CI caching mechanism) you need to define two secrets in Settings -> Secrets & variables -> Actions -> Repositories secrets:

  • CACHIX_CACHE_NAME: The cache name you created on cachix.org. This is free for public caches, which is acceptable for OSS repositories.

  • CACHIX_AUTH_TOKEN: The access token created on cachix.org for this cache CACHIX_CACHE_NAME.

Development

Read first the Contribution Guidelines.

For technical documentation on setup and development, see the Development Guide

Copyright

Copyright © 2025-2028 Swiss Data Science Center (SDSC), www.datascience.ch. All rights reserved. The SDSC is jointly established and legally represented by the École Polytechnique Fédérale de Lausanne (EPFL) and the Eidgenössische Technische Hochschule Zürich (ETH Zürich). This copyright encompasses all materials, software, documentation, and other content created and developed by the SDSC.