Skip to content

docs: add use cases, with the manual install the plugin replaces - #53

Merged
linghengqian merged 2 commits into
mainfrom
docs/usage-scenarios
Nov 3, 2026
Merged

linghengqian merged 2 commits into
mainfrom
docs/usage-scenarios

Conversation

@linghengqian

Copy link
Copy Markdown
Member

Adds a use-cases page that sets the plugin against installing Flutter by hand (download, unpack, a PATH line in ~/.bashrc) and goes through the situations it is for.

Changes

  • docs/use-cases.md and docs/zh-CN/use-cases.md, nine scenarios: a new machine (the five manual steps next to vfox add / install / use), a machine with a hand-made install, projects on different versions, a team on one version, upgrading and going back, a beta in one terminal, a mirror, scripts and IDEs, ARM64 and OpenHarmony.
  • README.md and README_CN.md: a "Use cases" section, a few sentences and a link, as for every other subject.
  • Two corrections to existing pages (both languages), found by running the commands:
    • versions.md said vfox does not add .vfox/ to the project's .gitignore. vfox 1.0.13 does when the project has one (Added '.vfox/' to .gitignore), and creates none.
    • A project's choice applies in the directory that holds .vfox.toml, not in its subdirectories, and only from the next prompt, so cd project && flutter run on one line still runs the previous directory's Flutter. Now in versions.md and in the "flutter is a different Flutter than vfox use says" entry of troubleshooting.md.

No code changes.

What the page says about ~/.bashrc

It does not claim that ~/.bashrc is never touched. vfox still has to be hooked into the shell once (eval "$(vfox activate bash)"), and vfox use stops without the hook (vfox requires hook support. ...). What the plugin saves is everything about Flutter: nothing is added to, edited in or removed from ~/.bashrc when you install, switch or uninstall, and a terminal that was already open picks the new choice up at its next prompt, where by hand each one has to source ~/.bashrc.

Verification

"Nothing in CI checks the docs, so run the commands you add", so they were run: Ubuntu 26.04.1 x64, vfox 1.0.13, plugin 0.2.5 from the registry, every run in a throwaway HOME (env -i), never the real ~/.vfox.

  • The five manual steps as written, with 3.47.4 and the CFUG host for speed: flutter --version --no-version-check runs. vfox install flutter@3.47.4 downloaded the identical file: the SHA-256 it verifies against the index (5b45f0ce…) is what sha256sum printed for the manual download.
  • Real 3.47.4 and 3.44.0 side by side: vfox use --project in two project directories (and vfox current flutter in a subdirectory), vfox exec without the hook, ~/.bashrc holding only the hook line afterwards, Flutter's settings in ~/.config/flutter and the pub cache in ~/.pub-cache, both outside the SDK.
  • Everything that depends on the hook ran in interactive Bash on a pty, one command per prompt: an already-open terminal picks up vfox use --global at its next prompt, the session scope stays in its terminal, cd and flutter on one line use the previous directory's PATH.
  • Install, stable / beta resolution, upgrade and rollback, vfox uninstall, vfox install --all for a teammate, and a hand-made install next to vfox (the hook before and after the export PATH line): against a fake mirror, the recipe in docs/development.md.
  • Relative links and anchors of the eight files, Chinese anchors included: 160 links, none broken. The new page against its Chinese twin: 16 code blocks identical, the same headings, the same inline code in each section.

What the runs turned up, and the page now avoids or explains:

  • flutter --version | head -n 1 prints a 35-line Broken pipe stack trace on Flutter's very first run, when it also prints its telemetry notice. The examples use sed -n 1p.
  • Without --no-version-check, the first run of an SDK older than the newest stable opens with the "A new version of Flutter is available! ... run flutter upgrade" box. The examples pass the flag, and the upgrade section points to the existing troubleshooting entry.
  • vfox install --all installs but does not select: the teammate still runs vfox use --project. On a machine without the plugin, the first --all only adds the plugin.

For review

  • Not run, because the machine is x64 Linux: the macOS, Windows and ARM64 commands. Those parts are prose and links to the existing pages.
  • The curl line on the page uses the Google host. It answers 200 with the same Content-Length as the CFUG host, and its first 60 MB downloaded; the complete download went through CFUG.
  • The page quotes stable = 3.47.9 and beta = 3.50.0-0.3.pre (2026-11-03, the same on Google's index and CFUG's) and vfox 1.0.13, dated like the other pages.
  • troubleshooting.md still says a manual install earlier in PATH wins. On Ubuntu with Bash, vfox 1.0.13 put its directory first in both orders (the hook before or after the manual export line), and the new page says so in its Ubuntu section. I left the existing sentence alone because macOS and Windows may differ. Narrow it if you agree.
  • Only Markdown changed, so the lint, license, hook-test and e2e jobs have nothing new to check.
  • The branch has one merge of main in it, to pick up Add a project OpenCode config allowing git push and PR create/comment #52's opencode.jsonc. The repo only allows squash merges, so it does not reach main.

- docs/use-cases.md and docs/zh-CN/use-cases.md: the five manual steps
  (download, unpack, a PATH line in ~/.bashrc) next to `vfox add`,
  `install` and `use`, then the situations the plugin is for: a machine
  with a hand-made install, projects on different versions, a team on
  one version, upgrading and going back, a beta in one terminal, a
  mirror, scripts and IDEs, ARM64 and OpenHarmony.
- README.md and README_CN.md: a "Use cases" section that links to it.
- versions.md and troubleshooting.md, both languages: vfox 1.0.13 adds
  `.vfox/` to an existing .gitignore, which versions.md denied, and a
  project's choice applies only in the directory that holds .vfox.toml,
  and only from the next prompt.

The commands were run on Ubuntu 26.04.1 with vfox 1.0.13 and plugin 0.2.5.
@linghengqian linghengqian added the documentation Improvements or additions to documentation label Nov 3, 2026
@linghengqian
linghengqian merged commit c2c1732 into main Nov 3, 2026
10 checks passed
@linghengqian
linghengqian deleted the docs/usage-scenarios branch November 3, 2026 05:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant