The SKIRT project
advanced radiative transfer for astrophysics
Contributing

Introduction

Thank you for reading this page and for considering a contribution to the open source SKIRT project. There are various valuable ways of contributing, such as:

  • Using the SKIRT code in your work and providing feedback about it.
  • Applying the code to various (possibly new) science cases and validating the results.
  • Reporting and helping to solve installation problems, usage questions, or bugs in the code.
  • Suggesting and discussing (preferably concrete and feasible) new features.
  • Correcting, improving, or adding to the documentation in the code or on the web site.
  • Fixing bugs or implementing new features (from just a few lines of code to whole modules).

The names of past and current contributors can be found here:

An overview of the project infrastructure is presented here:

The technical contribution mechanisms and workflows are discussed here:

For detailed developer information, including coding style guidelines and the recommended GitHub worklow, see the Developer Guide.

Contributor's hall of fame

Maarten Baes conceived of SKIRT and wrote the first several versions of the code, starting in 2002. He continues to determine the strategic direction and to supervise further development, heading the SKIRT Core Team. Once in a while, less frequently than he would like, he contributes some nice new feature himself.

Peter Camps was the main SKIRT developer for ten years (2012-2022) until he retired. He introduced its current design and added many capabilities.

The following people contributed to the SKIRT project effort by developing code, writing documentation, and/or by extensively using the code and offering detailed information on new features. They are listed in alphabetical order on last name.

  • Maarten Baes
  • Christopher Barber
  • Christoph Behrens
  • Killian Braun
  • Peter Camps
  • Marjorie Decleir
  • Gert De Geyter
  • Ilse De Looze
  • Jacopo Fritz
  • Andrea Gebek
  • Tom Hendrix
  • Anand Utsav Kapoor
  • Alexander Mosenkov
  • Christian Peest
  • Waad Saftly
  • Marko Stalevski
  • James Trayford
  • Ana Trčka
  • Bert Vandenbroucke
  • Bert Vander Meulen
  • Dries Van De Putte
  • Sebastiaan Vandewoude
  • Sam Verstocken
  • Sébastien Viaene

If we inadvertently failed to list someone, please let us know.

GitHub repositories

The SKIRT project repositories are hosted as part of the GitHub SKIRT organization. Next to the SKIRT and PTS source code, the source text for the web site is also placed in a repository, allowing contributions to the documentation through a workflow similar to that for source code. The following table lists the repositories in the SKIRT organization to which new contributions should be directed.

Repository Description
SKIRT9 SKIRT 9 C++ source code
PTS9 Python Toolkit for SKIRT 9
Web9 Additional documentation for the web site

Reference documentation is embedded in the source code as special comment blocks in Doxygen format, and is thus automatically contained in a GitHub repository as a part of the development cycle. All other documentation available on this web site is authored as a set of text files in Doxygen format (i.e. special comment blocks without actual source code). These Doxygen source files, together with any referenced images and the relevant Doxygen configuration files, are contained in a separate public repository as indicated in the table above.

Web site

All documentation related to the SKIRT project is published on the web site www.skirt.ugent.be, which is hosted on the Ghent University web server. Each repository in the GitHub SKIRT organization includes a makeHTML.sh procedure that drives Doxygen to locally build HTML pages from the comment blocks embedded in the source code or text files in the repository. This procedure converts LaTeX formulas to images, performing a full LaTeX syntax check along the way. As a result, this procedure enables contributors to verify changes in the documentation before initiating a pull request (assuming Doxygen is installed on their system).

To allow combining the documentation from the various repositories into a single web site, the Web9 repository also contains a stageWebsite.sh procedure to locally build the complete web site from a local copy of the relevant repositories (SKIRT9, PTS9, Web9). This procedure uses MATHJAX to render LaTeX formulas, which avoids the many images created by an explicit conversion, and leads to a much more pleasing formula presentation. While any contributor can stage the web site, assuming they have a local copy of all relevant repositories, only a SKIRT Core Team member can actually publish the web site because it requires write access rights to the web server.

Data

Because of size limitations on the Ghent University web server and in GitHub repositories, data files needed by the code and/or linked from the web site are handled separately and are hosted on the Ghent University science faculty data server. Examples of extra data files include:

  • External resources for SKIRT.
  • Example data used in tutorials on SKIRT or PTS.
  • Configuration, input and reference data for SKIRT benchmark tests.

These data files are prepared and published by a SKIRT Core Team member. There is at this point no automated workflow for other contributors to participate in this effort, although many of the procedures are available as part of PTS. For example, contributors can locally prepare and use new SKIRT stored table resource files by adjusting or extending the appropriate PTS functions.

GitHub teams

The GitHub SKIRT organization currently offers three access levels:

Any GitHub user Because the repositories are public, any GitHub user has read access and can post an issue or send a pull request
SKIRT Contributor Team Members of this team have access to the SKIRT Contributor Team page so that they can participate in project-wide discussions and receive SKIRT-related broadcast notifications
SKIRT Core Team Members of this team have push access rights to the repositories and are responsible for managing issues and pull requests (e.g., closing issues or merging pull requests)

Users with a specific interest in SKIRT are encouraged to become a member of the SKIRT Contributor Team. Notifications about important events (e.g., a new major feature becoming available, or an upcoming SKIRT user group meeting) will be broadcast to SKIRT Contributor Team members through the team page. The team page also facilitates discussions that are not directly related to a particular technical issue. For example, there could be discussions about a given SKIRT use case or about an upcoming conference in a related field.

To become a member of the SKIRT Contributor Team, contact the SKIRT Core Team (see Contact).

For more information on GitHub team discussions, see GitHub help.

GitHub issues

Usage questions, bug reports and feature requests are managed through the issues system offered by GitHub for each of the repositories listed in section GitHub repositories above. Anyone can post an issue, and anyone can respond. Users are encouraged to participate also by adding relevant information to issues posted by other users. Example contributions in this area include:

  • Suggesting solutions or workarounds for a problem posted by another user.
  • Providing extra information to a bug report (e.g., does it also happen on another operating system?).
  • Supporting feature requests, or suggesting alternative solutions.

The SKIRT Core Team is responsible for following up on and eventually closing issues as needed.

To post an issue:

  • Browse to the SKIRT repository for which this issue is relevant (see section GitHub repositories above).
  • Select the "Issues" tab.
  • Click the green "New Issue" button.
  • Select one of "Bug report", "Feature request", or "Usage question".
  • Add a title and complete all relevant sections in the provided template.
  • Click the green "Submit" button.

For more information on GitHub issues, see GitHub help.

GitHub pull requests

The repositories in the SKIRT organization use the GitHub fork and pull workflow model. Anyone can fork a repository, push changes to their personal fork, and initiate a pull request. The changes can be pulled into the original repository by a SKIRT Core Team member, possibly after discussion and/or being adjusted in one or more iterations.

To get started with contributing to one of the SKIRT project repositories:

  • On the GitHub web site, fork the relevant repository (see section GitHub repositories above).
  • Clone this personal fork to your computer, possibly replacing your direct clone of the original repository.

To initiate a pull request:

  • Make the desired changes, commit them, and push them to your personal fork.
  • Test your changes, and repeat the previous line as many times as needed.
  • On the GitHub web site, create a pull request from your fork.
  • Wait for feedback from the SKIRT Core Team.

This worklow is described in much more detail in The GitHub workflow for the SKIRT project.