contribution_guide.rst 4.48 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
.. Adapting from https://docs.sglang.ai/references/contribution_guide.html

Contribution Guide
==================

Welcome to **Nunchaku**! We appreciate your interest in contributing.
This guide outlines how to set up your environment, run tests, and submit a Pull Request (PR).
Whether you're fixing a minor bug or implementing a major feature, we encourage you to
follow these steps for a smooth and efficient contribution process.

🚀 Setting Up & Building from Source
------------------------------------

1. Fork and Clone the Repository

   .. note::

Muyang Li's avatar
Muyang Li committed
18
      As a new contributor, you won't have write access to the `Nunchaku repository <github_nunchaku_>`_.
19
20
21
22
23
24
25
26
      Please fork the repository to your own GitHub account, then clone your fork locally:

   .. code-block:: shell

      git clone https://github.com/<your_username>/nunchaku.git

2. Install Dependencies & Build

27
28
29
30
31
32
   To set up your development environment, follow the steps in :ref:`Installation <build-from-source>`.
   Be sure to install all development dependencies by running:

   .. code-block:: shell

      pip install -e ".[dev]"
33
34
35
36

🧹 Code Formatting with Pre-Commit
----------------------------------

37
38
We use `pre-commit <https://pre-commit.com/>`__ hooks to maintain consistent code style across the project.
Before submitting your changes, please ensure pre-commit is installed and run:
39
40
41

.. code-block:: shell

42
   pip install pre-commit  # This should already be installed with the development dependencies
43
44
45
   pre-commit install
   pre-commit run --all-files

Muyang Li's avatar
Muyang Li committed
46
47
- ``pre-commit run --all-files`` manually triggers all checks and automatically fixes issues where possible.
  If it fails initially, re-run until all checks pass.
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

- ✅ **Ensure your code passes all checks before opening a PR.**

- 🚫 **Do not commit directly to the** ``main`` **branch.**
- Always create a feature branch (e.g., ``feat/my-new-feature``),
- commit your changes there, and open a PR from that branch.

🧪 Running Unit Tests & Integrating with CI
-------------------------------------------

Nunchaku uses ``pytest`` for unit testing. If you're adding a new feature,
please include corresponding test cases in the ``tests`` directory.
**Please avoid modifying existing tests.**

Running the Tests
~~~~~~~~~~~~~~~~~

.. code-block:: shell

Muyang Li's avatar
Muyang Li committed
67
68
   HF_TOKEN=$YOUR_HF_TOKEN pytest -v tests/flux/test_flux_examples.py
   HF_TOKEN=$YOUR_HF_TOKEN python .github/workflows/run_all_tests.py
69
70
71

.. note::

Muyang Li's avatar
Muyang Li committed
72
73
   ``$YOUR_HF_TOKEN`` refers to your Hugging Face access token,
   required to download models and datasets.
74
75
76
77
   You can create one at https://huggingface.co/settings/tokens.
   If you've already logged in using ``huggingface-cli login``,
   you can skip setting this environment variable.

Muyang Li's avatar
Muyang Li committed
78
79
Some tests generate images using the original 16-bit models.
You can cache these results to speed up future test runs by setting the environment variable ``NUNCHAKU_TEST_CACHE_ROOT``. If not set, the images will be saved in ``test_results/ref``.
80
81
82
83

Writing Tests
~~~~~~~~~~~~~

Muyang Li's avatar
Muyang Li committed
84
85
86
When adding a new feature,
please include corresponding test cases in the ``tests`` directory.
**Please avoid modifying existing tests.**
87
88
89

To test visual output correctness, you can:

Muyang Li's avatar
Muyang Li committed
90
91
1. **Generate reference images:**
   Use the original 16-bit model to produce a small number of reference images (e.g., 4).
92

Muyang Li's avatar
Muyang Li committed
93
94
95
2. **Generate comparison images:**
   Run your method using the **same inputs and seeds** to ensure deterministic outputs.
   You can control the seed by setting the ``generator`` parameter in the diffusers pipeline.
96

Muyang Li's avatar
Muyang Li committed
97
98
99
100
3. **Compute similarity:**
   Evaluate the similarity between your outputs and the reference images
   using the `LPIPS <https://arxiv.org/abs/1801.03924>`_ metric.
   Use the ``compute_lpips`` function provided in `tests/flux/utils.py <https://github.com/nunchaku-tech/nunchaku/blob/main/tests/flux/utils.py>`_:
101

Muyang Li's avatar
Muyang Li committed
102
   .. code-block:: python
103
104
105

      lpips = compute_lpips(dir1, dir2)

Muyang Li's avatar
Muyang Li committed
106
107
108
109
110
111
   - ``dir1``: Directory containing the reference images.
   - ``dir2``: Directory containing the images generated by your method.

**Setting the LPIPS Threshold**

To pass the test, the LPIPS score should be **below a predefined threshold**—typically **< 0.3**.
112

Muyang Li's avatar
Muyang Li committed
113
114
115
116
- First, run the comparison locally to observe the LPIPS value.
- Set the threshold slightly above your observed value to accommodate minor variations
  (a margin of **+0.04** is generally sufficient).
- Note that, due to the small sample size, slight fluctuations are expected.
117

Muyang Li's avatar
Muyang Li committed
118
By following these guidelines, you help maintain the reliability and reproducibility of Nunchaku’s test suite.