Contributing to Quantum Toolbox in Julia

Quick Start

QuantumToolbox.jl is developed using the git version-control system, with the main repository hosted in the qutip organisation on GitHub. You will need to be familiar with git as a tool, and the GitHub Flow workflow for branching and making pull requests. The exact details of environment set-up, build process, and runtests vary by repository are discussed below. In overview, the steps to contribute are:

• Consider creating an issue on the GitHub page of the relevant repository, describing the change you think should be made and why, so we can discuss details with you and make sure it is appropriate.

• If this is your first contribution, make a fork of the relevant repository on GitHub (which will be called as origin) and clone it to your local computer. Also add our copy as a remote (let's call it qutip here): git remote add qutip https://github.com/qutip/<repo-name>.

• Start from the main branch in your local computer (git checkout main), and pull all the changes from the remote (qutip) repository (on GitHub) to make sure you have an up-to-date copy: git pull qutip main.

• Switch to a new git branch in your local computer: git checkout -b <branch-name>.

• Make the changes you want.

• Go through the following build processes (if the changes you made relates to any of them) locally in your computer to build the final result so you can check your changes work sensibly:

  • Write and make sure all the runtests pass. See here for more details.

  • Make sure all the changes match the Julia code format (style). See here for more details.

  • Improve and make sure the documentation can be built successfully. See here for more details.

  • Update changelog. See here for more details.

• Add the changed files to the git staging area git add <file1> <file2> ..., and then create some commits with short-but-descriptive names: git commit.

• Push the changes to your fork (origin): git push -u origin <branch-name>. You won’t be able to push to the remote (qutip) repositories directly.

• Go to the GitHub website for the repository you are contributing to, click on the “Pull Requests” tab, click the “New Pull Request” button, and follow the instructions there.

Once the pull request (PR) is created, some members of the QuTiP admin team will review the code to make sure it is suitable for inclusion in the library, to check the programming, and to ensure everything meets our standards. For some repositories, several automated CI pipelines will run whenever you create or modify a PR. In general, these will basically be the same ones which you can run locally, and all CI pipelines are required to pass online before your changes are merged to the remote main branch. There might be some feedbacks and requested changes. You can add more commits to address these, and push them to the branch (<branch-name>) of your fork (origin) to update the PR.

The rest of this document covers programming standards.

Runtests

All the test scripts should be located in the folder test in the repository. To run the test, use the following command under the root directory of the repository you are working on:

make test

This command will automatically rebuild Julia and run the script located in test/runtests.jl (should cover both the original tests and the new test(s) you add).

The tests are divided into several test groups, where the group names are defined in the file test/runtests.jl with a variable GROUP. One can also run the test scripts just for a certain test group by adding an argument GROUP=<test-group-name> to the make test command. For example, to run the tests for group Core, one can use the following command:

make GROUP=Core test

Test Item Framework for Core tests

The tests in GROUP=Core are provided using the Test Item Framework, which structures the test codes into @testitems and makes it easier to run individually.

The VS Code and its Julia extension provides us with options to run individual @testitems. It is much easier to find the specific core test that failed since the Julia extension in VS Code will collect all core test failures and then display them in a structured way, directly at the place in the code where a specific core test failed. See here for more details.

Julia Code Format

We use JuliaFormatter.jl to format all the source codes. The code style and extra formatting options is defined in the file .JuliaFormatter.toml in the repository.

To format the changed codes, use the following command under the root directory of the repository you are working on:

Requirements

If this is your first time running make command in the local repository you are working on or you just had reinstalled Julia, you should run make setup first.

make format

Documentation

All the documentation source files [in markdown (.md) format] and build scripts should be located in the folder docs in the repository.

The document pages will be generated in the folder docs/build/1/ (which is ignored by git) in the repository.

To instantiate and build the documentation, run the following command under the root directory of the repository you are working on:

Requirements

You need to install Node.js and npm first.

make docs

This command will automatically rebuild Julia and run the script located in docs/make.jl (should be able to build the necessary files for the documentation).

To read the documentation in a browser, you can run the following command:

make vitepress

This will start a local Vitepress site of documentation at http://localhost:5173 in your computer.

Update ChangeLog

The changelog is written in the file CHANGELOG.md in the repository. If you add some changes to the repository and made a PR, you should also add some messages or release notes together with the related PRs/issues entries to CHANGELOG.md. For example, add a new line in CHANGELOG.md:

- some messages to describe the changes. ([#issue-ID], [#PR-ID])

See also the ChangeLog page for more examples.

After that, you can run the following command under the root directory of the repository you are working on:

Requirements

If this is your first time running make command in the local repository you are working on or you just had reinstalled Julia, you should run make setup first.

make changelog

This will automatically generate the full URLs for the references to PRs/issues by utilizing Changelog.jl.

If the changes you made are not necessary to be recorded in CHANGELOG.md, you can add the label [Skip ChangeLog] to the PR you made in the GitHub repository.