update contrubution guide

Author: ytdHuang

README.md

@@ -174,7 +174,7 @@ Here we provide a brief performance comparison between `QuantumToolbox.jl` and o
 
 ## Contributing to QuantumToolbox.jl
 
-You are most welcome to contribute to `QuantumToolbox.jl` development by forking this repository and sending pull requests (PRs), or filing bug reports at the issues page. You can also help out with users' questions, or discuss proposed changes in the [QuTiP discussion group](https://groups.google.com/g/qutip).
+You are most welcome to contribute to `QuantumToolbox.jl` development by forking this repository and sending pull requests (PRs), or filing bug reports at the issues page. Contributors and users are invited to [![Zulip](https://img.shields.io/badge/chat-on%20Zulip-6f73af.svg)](https://quantumtoolbox-jl.zulipchat.com) for questions, development discussions, and community updates. You can also help out with users' questions, or discuss proposed changes in the [QuTiP discussion group](https://groups.google.com/g/qutip).
 
 For more information about contribution, including technical advice, please see the [Contributing to Quantum Toolbox in Julia](https://qutip.org/QuantumToolbox.jl/stable/resources/contributing).
 

docs/src/resources/contributing.md

@@ -1,7 +1,11 @@
 # [Contributing to Quantum Toolbox in Julia](@id doc-Contribute)
 
+[![Zulip](https://img.shields.io/badge/chat-on%20Zulip-6f73af.svg)](https://quantumtoolbox-jl.zulipchat.com)
+
 ## [Quick Start](@id doc-Contribute:Quick-Start)
 
+### [Git Tutorial](@id doc-Contribute:Git-Tutorial)
+
 `QuantumToolbox.jl` is developed using the [`git`](https://git-scm.com/) version-control system, with the [main repository](https://github.com/qutip/QuantumToolbox.jl) hosted in the [qutip organisation on GitHub](https://github.com/qutip). You will need to be familiar with [`git`](https://git-scm.com/) as a tool, and the [GitHub Flow](https://docs.github.com/en/get-started/quickstart/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.
@@ -13,16 +17,43 @@
     - Write and make sure all the runtests pass. See [here](@ref doc-Contribute:Runtests) for more details.
     - Make sure all the changes match the `Julia` code format (style). See [here](@ref doc-Contribute:Julia-Code-Format) for more details.
     - Improve and make sure the documentation can be built successfully. See [here](@ref doc-Contribute:Documentation) for more details.
-    - Update changelog. See [here](@ref doc-Contribute:Update-ChangeLog) for more details.
+    - Update changelog. See [here](@ref doc-Contribute:ChangeLog) 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.
+### [Make Command](@id doc-Contribute:Make-Command)
+
+!!! note "Install `make` in Windows"
+    The `make` command is not available by default on Windows. You will need to install a compatible version of `make` (for example via Git-for-Windows, MSYS2, or similar tools). A helpful reference for setting this up can be found here: https://stackoverflow.com/questions/66525016/how-to-run-make-command-in-gitbash-in-windows
+
+To simplify common developer tasks, `QuantumToolbox.jl` provides a set of predefined `make` commands. These commands are defined in the repository’s file called `Makefile` and offer a convenient interface for running documentation builds, tests, formatting, and other maintenance routines.
+
+If you are contributing for the first time, or have installed a fresh `julia` version, you should begin with:
 
-## [Runtests](@id doc-Contribute:Runtests)
+```shell
+make setup
+```
+
+to install necessary dependencies. Here are several other common commands:
+
+```shell
+make test      # run the tests
+make format    # format codes with JuliaFormatter
+make docs      # instantiate and build the documentation
+make changelog # generate changelog
+make help      # view all commands
+```
+
+Each command may accept additional options or environment variables to customize its behavior. The following sections describe these commands in detail and explain the available configuration options.
+
+## [Programming Standards](@id doc-Contribute:Programming-Standards)
+
+The rest of this document covers programming standards for `QuantumToolbox.jl`.
+
+### [Runtests](@id doc-Contribute: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:
 
@@ -38,13 +69,13 @@ The tests are divided into several test groups, where the group names are define
 make GROUP=Core test
 ```
 
-### [Test Item Framework for Core tests](@id doc-Contribute:Test-Item-Framework-for-Core-tests)
+#### [Test Item Framework for Core tests](@id doc-Contribute:Test-Item-Framework-for-Core-tests)
 
 The tests in `GROUP=Core` are provided using the [Test Item Framework](https://www.julia-vscode.org/docs/stable/userguide/testitems/), which structures the test codes into `@testitems` and makes it easier to run individually.
 
 The [VS Code](https://code.visualstudio.com/) and its [Julia extension](https://www.julia-vscode.org/) provides us with options to run individual `@testitems`. It is much easier to find the specific core test that failed since the [Julia extension](https://www.julia-vscode.org/) in [VS Code](https://code.visualstudio.com/) 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](https://www.julia-vscode.org/docs/stable/userguide/testitems/) for more details.
 
-## [Julia Code Format](@id doc-Contribute:Julia-Code-Format)
+### [Julia Code Format](@id doc-Contribute:Julia-Code-Format)
 
 We use [`JuliaFormatter.jl`](https://github.com/domluna/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.
 
@@ -57,7 +88,7 @@ To format the changed codes, use the following command under the *__root directo
 make format
 ```
 
-## [Documentation](@id doc-Contribute:Documentation)
+### [Documentation](@id doc-Contribute:Documentation)
 
 All the documentation source files [in markdown (`.md`) format] and build scripts should be located in the folder `docs` in the repository.
 
@@ -74,6 +105,13 @@ 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).
 
+One can also skip several processes in documentation build by adding arguments to the `make docs` command. For example,
+
+```shell
+make docs DOCTEST=false # skip doc tests
+make docs DRAFT=true    # disable cell evaluation
+```
+
 To read the documentation in a browser, you can run the following command:
 
 ```shell
@@ -82,7 +120,7 @@ make vitepress
 
 This will start a local Vitepress site of documentation at `http://localhost:5173` in your computer.
 
-## [Update ChangeLog](@id doc-Contribute:Update-ChangeLog)
+### [ChangeLog](@id doc-Contribute: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`: