Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
217 lines (151 loc) · 8.8 KB

CONTRIBUTING.md

File metadata and controls

217 lines (151 loc) · 8.8 KB
Raw

Contributing Guide

Contributions are welcome, if you find some bugs or have some ideas, please open an issue or submit a pull request.

Please ensure that you are using clean code, following the coding style and code organization in existing code, and make sure all the tests pass.

Please submit one PR that does one thing, this is important, and helps us to review your code more easily and push to merge fast.

AI Assistance

🤖 When you submit PR, please point out which parts are generated by AI, if any.

All code generated by AI must be reviewed and tested by humans, and should follow the same coding style and code organization as existing code.

The AI generated code without refactoring will be rejected.

Code Style

Before you start to write code, please read the existing code to follow the same coding style and code organization.

  • Inspired by existing code or refer to macOS/Windows controls API design to name your functions, properties, structs etc.

Development and Testing

System dependencies

The script folder contains some useful scripts to help you set up the development environment.

To install the system dependencies, run the following script:

./script/bootstrap

For Windows, you can run the following command in PowerShell:

.\script\install-window.ps1

Accessibility-driven UI testing

Use accessibility-driven interaction as the default manual UI testing method for focus, keyboard, selection, menu, and input behavior. See Accessibility-driven UI testing for the required Story app launch method, accessibility-tree workflow, and completion evidence.

Run story

There are a lot of UI test cases in the crates/story folder, if you change the existing features you can run the tests to make sure they are working.

Use cargo run to run the complete story examples to display them all in a gallery of GPUI components.

cargo run

Run single example

There is also available some split examples, run cargo run --example to see the available examples.

cargo run --example table

UI Guides

GPUI Component is inspired by macOS and Windows controls, combined with shadcn/ui design for a modern experience.

So please refer to the following UI guides when you design or change the UI components:

Rules

  • Use default mouse cursor not pointer for buttons, unless it's a link button, we are building desktop apps, not web apps.
  • Use md size for most cases and as the default.

Profile the performance

When you change the rendering code, please profile the performance to make sure the FPS is still good.

You can use MTL_HUD_ENABLED=1 environment variable to enable the Metal HUD to see the FPS and other performance metrics.

MTL_HUD_ENABLED=1 cargo run

NOTE: Only available on macOS with Metal backend, and the FPS is up limited your monitor refresh rate, usually 60 or 120.

Use Samply to profile the the performance

You can use Samply to profile the performance of the application to get more detailed information.

samply record cargo run

Use samply record command to start rust development, and do some operations in the app that you want to profile, then stop the terminal with ctrl-c, then samply will open the browser to show the profile results.

Release crates version

When we are ready to release a new version, please follow the steps below:

Use the script to bump the version(Recommended)

./script/bump-version.sh x.y.z

Manually bump the version

  1. Run cargo set-version to set the new version for all crates.

    cargo set-version x.y.z

  2. Git Commit the changes with message Bump vx.y.z.

  3. Create a new git tag with the version vx.y.z and push main branch and the tag to remote.

    git tag vx.y.z
git push origin vx.y.z

  4. Then GitHub Actions will automatically publish the crates to crates.io and create a new release in GitHub.

Publish GPUI pre-release crates from Zed

GPUI lives in the Zed repository, and Zed only publishes gpui to crates.io now and then. To depend on a newer GPUI from crates.io, publish a snapshot of any Zed commit under our own names:

Zed crate Published as
gpui gpui-pre
gpui_platform gpui-pre-platform
gpui_macros gpui-pre-macros
reqwest_client gpui-pre-reqwest-client
gpui_<x> gpui-pre-<x> (e.g. gpui-pre-macos)
other internal gpui-pre-<x> (e.g. gpui-pre-collections)

Every crate those four need is published together at one version, and each keeps its original crate name as the library name, so use gpui_kit::* works unchanged.

# Verify the latest Zed `main` without uploading anything.
./script/bump-gpui.ts --dry-run

# Publish from Zed `main` as the next <VERSION>.<N>.
./script/bump-gpui.ts

# Publish a specific Zed commit.
./script/bump-gpui.ts --rev 1662f5f3f6497c5f80830ccdca1edfd1fc0c6c6a

Every crate is published at <VERSION>.<N>, for example 0.3.12: the VERSION constant at the top of script/bump-gpui.ts (0.3) plus a patch number that continues from the highest one crates.io already has (0.3.0 first). A run that stopped part-way resumes the same number. Raise VERSION only when the crates should start a new minor series. A requirement such as version = "0.3.0" accepts every later 0.3.x, so consumers pick up new snapshots with cargo update. The Zed commit each build came from is recorded in every crate's description and [package.metadata.gpui-pre].

The Release GPUI workflow (.github/workflows/release-gpui.yml) runs this script every other Sunday (even ISO weeks) at 18:00 Beijing time and can be started by hand from the Actions tab, optionally with a Zed revision or an explicit version. It uses the repository's CARGO_REGISTRY_TOKEN secret.

Zed's reqwest fork is not part of the Zed workspace and is published by hand as gpui-pre-reqwest. The published gpui-pre-reqwest-client depends on it through the DEPENDENCY_OVERRIDES constant in the script; keep that version in step with the hand-published one.

The script runs on Bun and needs Cargo 1.90+ (for cargo publish --workspace) and a crates.io token from cargo login. It stages a standalone workspace in target/gpui-pre/workspace, audits its licenses, verifies it with cargo publish --dry-run, then builds and tests this repository against the staged crates (the same check, clippy and test commands CI runs, injected with --config patch.crates-io so nothing in the checkout changes), and only then uploads. Applications depend on gpui-pre with a caret requirement and pick up new snapshots on cargo update, so a Zed change that breaks gpui-component fails the release instead of reaching users; adapt the repository first, then publish. Pass --skip-kit-check only when you know why. crates.io only accepts a few brand-new crates per ten minutes, so the first run waits between batches; re-running resumes from where it stopped. Pass --zed <path> to reuse a local Zed checkout and --stage-only to inspect the generated workspace.

GPUI is Apache-2.0, and the snapshots are a redistribution of it, so the script keeps Zed's terms intact and refuses to publish anything else:

  • Every crate keeps its license, its repository and Zed's copyright notices, ships Zed's LICENSE-APACHE beside its sources, and would carry a NOTICE file if Zed added one. The Zed commit is recorded in the description and [package.metadata.gpui-pre], and the three files the script rewrites (gpui/src/action.rs, gpui_macros/src/lib.rs, gpui_apple/build.rs) start with a line saying what changed.
  • Staging fails if a selected crate is not Apache-2.0. Zed's application crates are GPL-3.0-or-later and live in the same workspace, so a new internal dependency can pull one into the closure; zlog did exactly that before Zed relicensed it.
  • The audit step runs cargo metadata on the staged workspace and fails on any copyleft dependency, whether it comes from Zed or from crates.io, so a license change upstream stops the release instead of reaching users.

Depend on the result with:

gpui = { package = "gpui-pre", version = "0.3.0" }
gpui_platform = { package = "gpui-pre-platform", version = "0.3.0" }
gpui_macros = { package = "gpui-pre-macros", version = "0.3.0" }