What to do when stuff breaks#

Motivation#

The group maintains a complex software stack that includes multiple jupyterhubs, parallel computation setup, gitlab, chat, websites, and more. As a consequence of the complexity, things break or people make mistakes because our resources don’t explain how stuff should be used. Problems like this are never unique, and therefore we save everyone’s effort by treating them systematically.

Follow this guideline whenever you encounter a part of the infrastructure that does not work or when you have a question about how to make things work. Ignoring this guideline may mean that:

  • Your issue is not addressed properly, and you keep spending effort and time on it.

  • The next person encountering the same issue wastes their time.

  • Those that can help spend more time than they should.

If you curate a part of the infrastructure, direct those approaching you with questions to this guideline.

Checklist#

Open an issue#

First, identify where you should report the problem or ask a question.

Remarks:

  • Don’t worry if you are unsure: we’ll move the issue where it belongs.

  • Check if a similar issue already exists

Your issue should contain:

  • A description of what you are trying to do

  • What doesn’t work

  • What you tried so far

Discuss the problem#

The most likely relevant channel is ~infrastructure

Collaborate with others#

Don’t take infrastructure maintenance for granted: try things, Google for related issues, report issues to other packages.

Report any progress or workarounds in the issue#

  • If you find a workaround, write it down.

  • If you execute terminal commands attempting to solve the issue, copy those.