--- format: markdown title: Collaboration on the GOLEM tokamak ... # Collaboration on the GOLEM tokamak *How students and colleagues work together on the software, diagnostics and documentation of the tokamak GOLEM. Valid from November 2026.* GOLEM is a university experiment. Most of what runs it has been written by students, often one generation after another. This page describes how that work is shared, so that everyone can contribute independently while the machine keeps running safely and nobody overwrites anyone else's work. ## In a nutshell 1. **Everyone works in their own copy.** Clone the repository to your own computer and work on a branch of your own. 2. **Nothing reaches the machine without review.** Push your branch to GitLab and open a *merge request* to `master`. The operator reviews it, verifies it on the server, merges it and deploys it. 3. **Real hardware is touched only with the operator present.** Your own computer runs everything in simulation, so experiment freely there. 4. **Each of us is responsible for a part.** You own your diagnostic or subsystem: its code, its documentation and the answer to "why did it do that?". ## The projects | What | Where | Notes | |---|---|---| | **Conductor**: control and record system of the tokamak (since autumn 2026) | [gitlab.com/golem-tokamak/conductor](https://gitlab.com/golem-tokamak/conductor) | Start with `README.md`, `AGENTS.md` and the README of the module you work on. Technical details are in `CONTRIBUTING.md` in the repository. | | **Dirigent**: the previous control system | [gitlab.com/golem-tokamak/dirigent](https://gitlab.com/golem-tokamak/dirigent) | Being replaced by Conductor; its scripts remain the reference for how the hardware is driven. See the [old housekeeping rules](/wiki/Handling/SWinfastructure/git/housekeeping_rules). | | **This wiki** | [golem.fjfi.cvut.cz/wiki](/wiki/) | Anyone with an account can edit. Larger reorganisations: ask first. | ## Getting started 1. Create a [GitLab](https://gitlab.com) account (or use the one you have) and send your user name to Petr Mácha, who manages the `golem-tokamak` group. He will add you to it. 2. Clone the project into a directory of its own and create a simulation-only installation beside it: ``` mkdir tG && cd tG git clone git@gitlab.com:golem-tokamak/conductor.git conductor/deploy/new-local-installation.sh ``` 3. Install the Python environment and run it in simulation (details in `CONTRIBUTING.md`): ``` cd conductor python3 -m venv --without-pip .venv python3 -m pip --python .venv install -r requirements.txt ./Cn shift status ./OperatorPanel --target simulation ``` No hardware is reachable from a simulation installation, so nothing can break. 4. Set your own identity in Git, so that your commits carry your name: ``` git config --global user.name "Your Name" git config --global user.email "you@example.org" ``` 5. Read the code of the module you are responsible for and the documents it points to. ## Working on a change - **One branch per piece of work**, started from the current `master` and named after what it does (for example `diagnostics/electrostatic-probes`). Keep it short-lived. A branch that drifts from `master` for weeks becomes hard to merge. - **Develop on your own computer, not on the lab server.** The server runs the machine, and its shared account is not your identity. - **AI assistants are welcome** (Claude Code, Cursor, Copilot and similar). The repository contains `AGENTS.md` with the rules an assistant must follow. Ask your assistant to read it first. You remain the author: read and understand what you commit. - **Run the whole test suite** before you push (the command is in `CONTRIBUTING.md`; GitLab runs it on every push too). - **Write in English** in the repository: code, comments, commit messages and documentation. Talk to each other in any language you like. - **Keep your machine out of shared code.** No paths, user names or host names of your computer. Hardware addresses, calibrations and experimental setups belong to the installation on the server, which the operator maintains. If you need one changed, say what and why. - **Readability for students is a requirement, not a nicety.** The next student must be able to find where things happen and follow the control flow. Prefer plain, explicit code and keep your module's `README.md` true. ## Submitting a change 1. Push your branch to GitLab. 2. Open a **merge request** into `master`. Describe what changes, why, and how you tested it. 3. The operator reviews it, runs it on the server in simulation (`deploy/verify-on-server.sh`), and either asks for changes or merges it. 4. After the merge the operator deploys the new version to the machine (`/tG/Conductor`). 5. The first test on real hardware is done together with the operator, during a shift. ## Hardware and the machine - The tokamak, its power supplies, capacitor banks, vacuum system and diagnostics are operated **only by or with the operator**. - Do not switch relays, send commands to devices, open or close shifts and sessions, or fire discharges on your own, from Conductor or otherwise, unless the operator has explicitly agreed to it for that occasion. - If you work in a session shared with the operator (for example a shared terminal), ask for confirmation before any such step. Do not assume it. ## Who is responsible for what The current list of who looks after which diagnostic, subsystem or piece of software is on the [Staff](/wiki/Staff/index) page. When you take responsibility for something, add yourself there. ## Questions If something in the documentation is unclear, say so: open an issue on GitLab or write to Vojtěch Svoboda. Feedback on what was hard to understand is as valuable as code.