Project Guidelines

This document aims at establishing common guidelines concerning the code production for future projects running on ACSS compute servers and, ideally, migration of current ones. As of now, these guidelines concern version control, package management, tensor back-end and project architecture.

Note should be taken that this document provides general guidelines and therefore absolute compliance is not mandatory. However, if you do not have a good reason to break them, please follow these instructions.

These guidelines are also available as a PDF.

Version control#

Code for projects of the team — and, when relevant, other resources — should be available as Git repositories on the team's GitHub. This requirement can be mitigated when collaborating with other researchers outside of the team. However, presence of a well-documented versioning of the project is mandatory, whether the repository is public or private.

The repository should not contain any data which can be re-constructed or downloaded automatically. This is especially true for sensitive data which should always be excluded in your .gitignore file.

When the Git repository is made available publicly, do not forget to add an appropriate license and instructions to facilitate re-use of your code.

Package management#

In Python#

First, note that development in Python should always be conducted inside a virtual environment. Coding and installing libraries on the global environment is considered bad practice for multiple reasons, including version conflicts between multiple installations of the same package and incompatibilities between different requirements. These types of issues can alter your capability to work on multiple projects. This is further accentuated on shared resources like our cluster where, in certain cases, you risk breaking others' projects.

Concerning Python package management, we recommend the use of UV as an alternative to pip or conda. The main benefits of this tool are:

• Speed: While usual package managers for Python are written in Python, UV is written in Rust and is therefore much faster to execute. Additionally, UV allows downloads and installations to be run in parallel, therefore further accelerating the setup process.

• Automated locking: UV automatically produces a pyproject.toml config file and a uv.lock locking file. These files are updated every time a new package is added. Additionally, these files allow to force the use of a Python version, which further facilitates the reproduction of an environment on a new computer.

• Easy transition: UV allows easy transition from pip by simply prefixing pip commands with "uv". Additionally, pip requirements files can be interpreted by UV to setup your environment. In a project initialised with uv init, typing uv add -r requirements.txt installs the packages from a pip requirements file into a UV environment and updates the pyproject.toml and uv.lock files accordingly.

Tensor back-end#

PyTorch is already used by many ACSS projects and we therefore recommend to use it for future ones too. The objective is to facilitate knowledge sharing by using the same tensor back-end. However, if a library used for a project is based on TensorFlow or Keras, it can be better for consistency and performance to use the same tensor back-end in this project.

Project architecture#

Upon creating new code repositories for data science projects, we recommend to use the Data Science Lifecycle Project (DSLP) template.

DSLP describes itself as "a set of prescriptive steps and best practices". While some of its functionalities are a bit too complex for projects involving 2 or 3 people, there are useful features that we highly recommend to use for all projects:

• Folder arborescence: The DSLP template has a very well-documented and well-developed folder structure. Following this structure on all our projects allows us to improve the maintainability of each of them, even if some folders are not relevant for a given project and can be discarded.

• PR and issue templates: DSLP provides a variety of issue and pull request templates. These templates can be used to document the evolution of the project easily.

DSLP provides a very useful guide as a series of Markdown documents to help start and develop projects.