Ways to contribute
- Report a bug or suggest a feature in the issue tracker.
- Ask a question in an issue or in Discussions.
- Submit code, as described below.
Set up
1
Fork and clone
Fork YoursshLabs/yourssh and clone your fork.
2
Get the app running
Follow Build from source.
3
Branch from develop
Branches
developis the working branch. Open your pull requests againstdevelop.masteris the release branch. Maintainers cut releases by mergingdevelopintomaster, and every push tomasterpublishes a release.
Pull requests
Before you open a pull request:-
flutter analyzereports no new warnings or errors. -
flutter testpasses, plus the tests of any package you changed. -
bash tool/check_ui_lint.shpasses (see below). - New or changed behavior has tests. Keep pure logic separate from Flutter and I/O so you can unit-test it; look in
app/test/for patterns. - UI changes include a screenshot. The app is dark only.
- No secrets, credentials, hostnames or personal data in code, tests or screenshots.
Titles and commits
Pull request titles and commit messages follow Conventional Commits:Local forks
dartssh2, xterm and flutter_pty are local forks that carry specific patches. If your change touches one, explain in the pull request why it can’t be solved in app/, and link the upstream issue when there is one.
Code style
- Match the surrounding code: naming, structure and comment density.
- Keep widgets, providers and services in their established folders under
app/lib/. - State management uses
providerwithChangeNotifier. Follow the existing patterns.
UI and the design system
New or rebuilt UI is built from forui widgets orYs* components from packages/yourssh_ui, not hand-styled Material. Use YsColors tokens instead of color literals, showYsToast for toasts and showYsDialog or showYsConfirm for dialogs. See the design system section.
UI lint gate
tool/check_ui_lint.sh scans app/lib and the Snippets, DevOps and Web Tools packages. It fails on the Material widgets the design system replaced: IconButton(, AlertDialog(, SnackBar(, Icons., ScaffoldMessenger, showDialog(, showModalBottomSheet and TextField(. The forui equivalents, such as FTextField( and showYsDialog(, pass. A justified exception goes in tool/ui_lint_allowlist.txt as path:pattern # reason, and needs a good reason.
Documentation
This documentation lives in its own repository, YoursshLabs/docs, separate from the app. If your change alters user-visible behavior, update the matching page there or mention it in your pull request. To preview the docs locally, runnpx mint dev in that repository; CI runs mint validate and mint broken-links on every pull request.
Releases
Maintainers handle releases: aCHANGELOG.md entry, a version bump in app/pubspec.yaml, and the merge from develop to master. Contributors don’t need to do any of this.