MyGoNavi/CONTRIBUTING.md

Contributing Guide

Thank you for contributing to this project.

This repository follows a release-first workflow: main is the default public branch, while releases are prepared through release/* branches.

---

Branch Model

• main: stable release branch and default branch
• dev: day-to-day integration branch for maintainers
• release/*: release preparation branches for maintainers
• Recommended branch names for external contributors:
  • fix/*: bug fixes
  • feature/*: new features or enhancements

Maintainer release flow:

feature/* / fix/* -> dev -> release/* -> main -> tag(vX.Y.Z)

---

How External Contributors Should Open Pull Requests

Whether your branch is fix/* or feature/*, external contributors should open pull requests directly against main.

Reasons:

• main is the default branch, so the PR entry point is clearer
• merged contributions are immediately visible on the default branch
• maintainers can handle downstream sync and release preparation in one place

Recommended flow:

1. Fork this repository
2. Create a branch in your fork (fix/* or feature/* is recommended)
3. Make your changes and perform basic self-checks
4. Push the branch to your fork
5. Open a pull request against the main branch of this repository

---

Pull Request Requirements

Please keep each pull request focused, reviewable, and easy to validate.

Recommended expectations:

• one pull request should address one logical change
• use a clear title that explains the purpose
• include the following in the description:
  • background and problem statement
  • key changes
  • impact scope
  • validation method
• include screenshots or recordings for UI changes when helpful
• explicitly mention risk and rollback notes for compatibility, data, or build-chain changes

---

Merge Strategy for Maintainers

Pull requests merged into main should generally use Squash and merge.

Reasons:

• keeps main history clean and linear
• maps each PR to a single commit on main
• reduces release, audit, and rollback complexity

---

Maintainer Sync Rules

Because external pull requests are merged directly into main, maintainers must sync main back to development and release branches to avoid branch drift.

1. Sync main -> dev (required)

This repository provides automatic sync via GitHub Actions workflow:

• .github/workflows/sync-main-to-dev.yml
• Trigger: every push to main
• Behavior: create/reuse a PR from main to dev; if mergeable, it tries to enable auto-merge
• Prerequisite: in Settings -> Actions -> General -> Workflow permissions, enable Allow GitHub Actions to create and approve pull requests; otherwise the workflow will skip PR creation and only emit a warning summary

Manual fallback (when conflicts or automation is unavailable):

git checkout dev
git pull
git merge main
git push

2. Create release/* from dev

Before a release, create a release branch from dev, for example:

git checkout dev
git pull
git checkout -b release/v0.6.0
git push -u origin release/v0.6.0

3. Release from release/* back to main

When release preparation is complete, merge the release branch back into main and create a tag:

git checkout main
git pull
git merge release/v0.6.0
git push
git tag v0.6.0
git push origin v0.6.0

4. Sync main back to dev after release

After the release, the same automation still applies. If needed, you can run the workflow manually (workflow_dispatch) or execute the fallback commands:

git checkout dev
git pull
git merge main
git push

---

Commit Message Recommendation

Keep commit messages clear and easy to audit.

Recommended format:

emoji type(scope): concise description

Examples:

🔧 fix(ci): fix DuckDB driver toolchain on Windows AMD64
✨ feat(redis): add Stream data browsing support
♻️ refactor(datagrid): optimize large-table horizontal scrolling and rendering

---

Additional Notes

• Please include validation results for documentation, build-chain, or driver compatibility changes
• For larger changes, opening an issue or draft PR first is recommended
• Maintainers may ask contributors to narrow the scope if the change conflicts with the current project direction

Thank you for contributing.