# Local development

How to edit the SDKs and an app at the same time, and see the change in the
running app straight away — no push, no tag, no `ref:` bump while you iterate.


## The setup

Your app keeps depending on the SDKs the normal way, as pinned git deps (see
[Install](../README.md#install)):

```yaml
dependencies:
  garage_ui:
    git:
      url: https://git.imbenji.dev/IMBENJI.NET/Garage-SDKs.git
      path: garage_ui
      ref: b2692019197e60d44ddd3ecab4917caf71ff45c3 # v0.1.0
```

Leave that alone. Clone this repo somewhere, then next to the app's
`pubspec.yaml` add a `pubspec_overrides.yaml` that points the packages you're
working on at the local checkout:

```yaml
# local garage sdks, so edits hot reload without a push. gitignored, never commit
dependency_overrides:
  garage_ui:
    path: ../Garage-SDKs/garage_ui
```

The path is relative to the app's folder, so adjust it to wherever your checkout
actually lives. If there's a space anywhere in it, quote it:

```yaml
    path: "../../Documents/Projects/Garage Services/SDKs/garage_ui"
```

pub reads `pubspec_overrides.yaml` on its own, you dont pass it anything. Run
`flutter pub get` and you should see a line per override:

```
! garage_ui 0.1.0 from path ../Garage-SDKs/garage_ui (overridden in ./pubspec_overrides.yaml)
```

If that line isn't there, the override isn't active — check the path.


## Overriding auth, entitlements or iap

`garage_entitlements` and `garage_iap` both depend on `garage_auth` by path
(`path: ../garage_auth` in their pubspecs). So the moment you override either
one, the local copy pulls in a local `garage_auth` too — and your app is still
asking for the git one. pub sees `garage_auth` from two sources and refuses.

The rule: **if you override `garage_entitlements` or `garage_iap`, override
`garage_auth` as well.**

```yaml
dependency_overrides:
  garage_auth:
    path: ../Garage-SDKs/garage_auth
  garage_entitlements:
    path: ../Garage-SDKs/garage_entitlements
  garage_ui:
    path: ../Garage-SDKs/garage_ui
```

`garage_ui` doesnt depend on any of the others, so it can be overridden on its
own.


## Hot reload

- Changed `pubspec_overrides.yaml` (added, removed, or edited a path)? Run
  `flutter pub get`, then do a full restart of the app. Hot reload wont pick up
  a dependency swap.
- After that, edits inside the SDK checkout behave like your own app code. Save
  and hot reload.
- Same caveats as app code: if the change is in something that only runs once
  (`main()`, initial state, a `const` widget tree), hot restart instead.


## Gitignore it

Add this to the app's `.gitignore`:

```
pubspec_overrides.yaml
```

The path in it only exists on your machine. Commit it and every other checkout
breaks, and so does any CI job or Docker image build, because none of them have
your local SDK checkout sitting next to the app.

While the override is active, `pubspec.lock` records the path source instead
of the git one. Thats expected. Just dont ship a lockfile in that state — see
below.

Also: never edit the copies under `~/.pub-cache/git`. pub treats that folder as
disposable and will overwrite or delete it without asking, and your app isn't
necessarily even reading from the copy you changed. Edit a real checkout and
override to it.


## Shipping an SDK change

Once the change works locally:

1. Commit and push it in this repo.
2. Tag a new version, e.g. `v0.1.1`, and push the tag.
3. In each app that should get it, bump `ref:` to the new tag's full commit hash. Do it on purpose,
   per app — dont float `main`.
4. Check the app builds **without** the override. Move it aside, resolve against
   the real tag, and analyze:

   ```sh
   mv pubspec_overrides.yaml pubspec_overrides.yaml.off
   flutter pub get
   flutter analyze
   ```

   This is the step that catches a forgotten push, a tag on the wrong commit, or
   a `ref:` you missed. It also puts `pubspec.lock` back on the git source.
5. Deploy, then move the override back if you're carrying on.


## Running the SDKs' own tests

These have tests:

```sh
cd garage_entitlements && flutter test
cd garage_iap && flutter test
cd garage_ui && flutter test
```

`garage_auth` has no `test/` dir yet.

There are two examples, both minimal wiring references rather than full apps:

- `garage_auth/example/main.dart` — a single file showing `GarageAuth` wired
  into an app. It has no pubspec of its own.
- `garage_iap/example` — a small package wiring `garage_auth` + `garage_iap`
  together by path. `flutter pub get` and `flutter analyze` in there is a quick
  way to check the two still fit together.