2025-09-08 10:16:11 +08:00
# Contributing Guide
2025-03-26 21:46:42 +08:00
2025-07-01 19:14:34 -07:00
Contributions are welcome, if you find some bugs or have some ideas, please open an issue or submit a pull request.
2025-03-26 21:46:42 +08:00
2025-07-01 19:14:34 -07:00
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.
2025-03-26 21:46:42 +08:00
2025-09-08 10:16:11 +08:00
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.
2025-03-26 21:46:42 +08:00
## Development and Testing
2025-10-17 11:43:07 +08:00
### 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:
``` bash
./script/bootstrap
```
For Windows, you can run the following command in PowerShell:
``` powershell
. \ script \ install-window . ps1
```
2025-03-26 21:46:42 +08:00
### Run story
2025-10-17 11:43:07 +08:00
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.
2025-07-01 19:14:34 -07:00
Use `cargo run` to run the complete story examples to display them all in a gallery of GPUI components.
2024-12-16 20:33:14 +08:00
``` bash
cargo run
```
2025-03-26 21:46:42 +08:00
### Run single example
2025-07-01 19:14:34 -07:00
There is also available some split examples, run `cargo run --example` to see the available examples.
2024-12-16 20:33:14 +08:00
``` bash
2025-03-26 21:46:42 +08:00
cargo run --example table
2024-12-16 20:33:14 +08:00
```
2025-09-08 10:16:11 +08:00
## 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:
- [Apple Human Interface Guidelines ](https://developer.apple.com/design/human-interface-guidelines/ )
- [Microsoft Fluent Design System ](https://learn.microsoft.com/en-us/windows/apps/design/ )
- [shadcn/ui ](https://ui.shadcn.com/ )
### 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.
2025-09-09 14:56:42 +08:00
## 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.
``` bash
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 ](https://github.com/mstange/samply ) to profile the performance of the application to get more detailed information.
``` bash
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.
2025-10-09 15:20:34 +08:00
## Release crates version
When we are ready to release a new version, please follow the steps below:
2025-10-24 11:35:59 +08:00
### Use the script to bump the version(Recommended)
``` bash
./script/bump-version.sh x.y.z
```
### Manually bump the version
2025-10-09 15:20:34 +08:00
1. Run `cargo set-version` to set the new version for all crates.
```bash
2025-10-24 11:35:59 +08:00
cargo set-version x.y.z
2025-10-09 15:20:34 +08:00
` ``
2025-10-24 11:38:18 +08:00
2. Git Commit the changes with message ` Bump vx.y.z`.
2025-10-24 11:35:59 +08:00
3. Create a new git tag with the version ` vx.y.z` and push ` main` branch and the tag to remote.
2025-10-09 15:20:34 +08:00
` ``bash
2025-10-24 11:35:59 +08:00
git tag vx.y.z
git push origin vx.y.z
2025-10-09 15:20:34 +08:00
` ``
4. Then GitHub Actions will automatically publish the crates to crates.io and create a new release in GitHub.
