Chillcraft/catppuccin-gtk
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
catppuccin-gtk/docs/CONTRIBUTING.md
iruzo cadc3e2ac2 perf: improving performance, layout (#215) 
Co-authored-by: nullishamy <git@amyerskine.me>
2024-06-01 19:49:55 +01:00

4.3 KiB
Raw Permalink Blame History

Development

Information regarding the architecture of the project can be found in the ARCHITECTURE.md document.

Requirements

Project structure

sources/ contains all of the source files needed for the project to build, including the Colloid submodule. It also contains our patches for Colloid, alongside the core build system implemented by us to replace the one from Colloid.

build.py is the entrypoint to the build system, placed at the root for convenience. The plumbing this utilizes is in sources/build.

install.py is our officially supported install script, which will automate the process of pulling the release, extracting it, and optionally adding symlinks for GTK-4.0 support. This script intentionally has no dependencies other than Python 3 itself. This keeps the end user experience simple and reproducible. Do not add external dependencies to this script.

Patching colloid

Tip

If you need to change the patches, reset the submodule and rerun the build script.

We patch upstream colloid through a series of .patch files, applied through git apply once when the build begins. The patches are located in ./patches/colloid/.

Once the build script patches the submodule, it will write a file into colloid/.patched, to signal to future invocations that the patches have already been applied.

The palette patches are generated through whiskers, so if you're changing them, they will need regenerated. Simply run whiskers palette.tera to rebuild them.

The process for building the theme is documented in the README.

Upstreaming procedure

Now and again, Colloid will have bugs upstream that impacts our theme. With our patching system we can easily fix these problems, but we still want to contribute the fixes upstream to benefit all users & forks of Colloid.

To avoid stalling unnecessarily, our procedure for the above is as follows:

  1. Open a PR to fix the issue, by adding a patch file to our theme, add upstream:intended to signal these changes are to be sent to Colloid eventually.

  2. Merge the PR & close the issue in our theme pertaining to the issue, once reviewed and approved

  3. Open a PR in Colloid with the patch

  4. Open a new issue in our theme, with these details:

    • The initial issue in our theme
    • The PR in Colloid that fixes the issue there
    • The PR that fixed the issue in our theme

    Add the upstream:open label

  5. Once the PR is merged in Colloid:

    1. Test that the issue no longer persists, without our patch
    2. Open a PR to remove the patch file in our theme, with these details:
      • The tracking issue
      • The commit that fixed the issue in Colloid
    3. Close the tracking issue & merge the PR to remove the patch file

Running test builds

We support building and publishing test builds from PRs. When you open PRs, the CI will automatically build with your changes and push an artifact which bundles all of the produced themes.

You can then download the artifacts as a zip (result should look similar to 7bff2448a81e36bf3b0e03bfbd649bebe6973ec7-artifacts.zip) and pass the path into install.py under the --from-artifact option:

python3 install.py mocha blue --dest ./build --from-artifact ~/downloads/7bff2448a81e36bf3b0e03bfbd649bebe6973ec7-artifacts.zip

This will take the target flavor / accent out of the zip, and install it using the regular install process.

It is advised to pass a --dest when running in this mode, because the released zips follow the exact same naming scheme as regular builds. This wil cause conflicts when you install, if you already had that theme installed. Passing a different destination allows you to move the extracted folders to ~/.local/share/themes yourself, adding a suffix as appropriate to avoid conflicts.

Warning

If you pass --link to the install script when working from a PR, it will forcibly overwrite your ~/.config/gtk-4.0/ symlinks. You will have to reinstall / relink to revert this.

Useful resources