Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
121 lines (88 loc) · 5.16 KB

CONTRIBUTING.md

File metadata and controls

121 lines (88 loc) · 5.16 KB
Raw

Contributing to RSerial Debug Assistant

中文文档

Thanks for your interest in contributing! This document explains how the repository is organized and the workflow to follow for new features, fixes, and releases.

Branch model (git-flow)

This repository is managed with a standard git-flow branch structure (using main as the production branch, in place of the historical master):

Branch git-flow role Purpose
main master (production) Shippable line. Only code that is meant to ship lands here. Never commit directly — always via pull request.
develop develop Day-to-day integration branch, and the GitHub default branch. All feature work is merged here first.
feature/<name> feature branches New features or improvements, branched from develop, merged back into develop via PR.
bugfix/<name> bugfix branches Non-urgent fixes, branched from develop, merged back into develop via PR.
release/<x.y.z> release branches Release preparation / version bump, branched from develop, merged into main via PR, then merged back into develop.
hotfix/<x.y.z> hotfix branches Urgent production fixes, branched from main, merged back into main via PR, then merged back into develop. 
feature/* ──PR──► develop ──PR──► release/x.y.z ──PR──► main ──tag Vx.y.z──► CI builds installers
bugfix/*  ──PR──► develop            │
hotfix/*  ──PR──► main ──tag──► CI   └─merge back──► develop
                  └─merge back──► develop

Optional: git-flow CLI setup

If you use the git-flow CLI, run these once after cloning to match the repo's branch names:

git config gitflow.branch.master main
git config gitflow.branch.develop develop
git config gitflow.prefix.feature feature/
git config gitflow.prefix.bugfix bugfix/
git config gitflow.prefix.release release/
git config gitflow.prefix.hotfix hotfix/
git config gitflow.prefix.support support/
git config gitflow.prefix.versiontag V

The CLI is entirely optional — plain git checkout -b ... + pull requests follow the exact same model.

Developing a new feature

  1. Fork the repository and clone your fork.
  2. Make sure your local develop is up to date: 
    git checkout develop && git pull
  3. Create a feature branch from develop: 
    git checkout -b feature/your-feature-name
# or with the CLI: git flow feature start your-feature-name
  4. Make your changes and test them locally (see Local development).
  5. Commit using Conventional Commits.
  6. Push and open a pull request targeting develop (never main).
  7. After review and merge, delete the feature branch.

Commit messages

Use Conventional Commits, as in the existing history:

feat(macos): add dual-platform release CI and serial port fixes
fix: handle serial port disconnection gracefully
docs: update usage guide
ci(macos): sign and notarize the GitHub dmg

Common types: feat, fix, docs, ci, refactor, test, chore.

Version numbers

When preparing a release, these four files must carry the same x.y.z:

  • version.json
  • src-tauri/Cargo.toml
  • src-tauri/tauri.conf.json
  • frontend/package.json

Do not add version numbers or changelogs to the README files — releases and changelogs live on GitHub Releases, generated by CI.

How a release ships (maintainers)

Full details, including the CI gate conditions and macOS signing, are in .github/BRANCHING.md. In short:

  1. Create release/x.y.z from develop, bump all four version files, PR into main.
  2. Tag the merge commit on main as Vx.y.z (capital V, matching version.json) and push the tag.
  3. CI verifies the gate (commit on main + version.json changed + tag matches) and builds the Windows .exe and macOS .dmg.
  4. Merge main back into develop.

Hotfixes

  1. Branch hotfix/x.y.z from main (not from develop).
  2. Fix, bump the patch version in all four files, PR back into main.
  3. Tag the new Vx.y.z on main and push — CI ships it.
  4. Merge main back into develop so the fix is not lost in development.

Local development

Prerequisites: Node.js, Rust toolchain, and the Tauri 2 system dependencies.

# Terminal 1 — frontend dev server (port 5173)
cd frontend && npm install && npm run dev

# Terminal 2 — Tauri app
npx @tauri-apps/cli@2 dev

Before committing:

  • Rust: run cargo fmt and cargo clippy in src-tauri/.
  • Frontend: follow the existing TypeScript / React conventions; prefer the shadcn components in frontend/src/components/ui/ over hand-written native elements.
  • Test on your platform; mention untested platforms in the PR description.

Reporting issues

Please open an issue with a clear title, reproduction steps, expected vs actual behavior, and your OS / app version.