Part 4: GitPortal App Developer Workflow

The basic concept behind the bidirectional configuration is that a developer can edit the Android or iOS app, including the KMP code, without being overly concerned with impacting the “other” app. More importantly, when making KMP changes to one app, you don’t need to immediately implement those changes in the other app.

In summary, when editing the Android app, you just edit the Android app. Same for iOS. You also should not need to modify your current team workflow.

Editing App Code

We’ll assume a basic git workflow. Update main, make changes in a feature branch, submit a PR for code review, then merge back into main (squash, rebase, whatever).

Using your IDE of choice, open the Android app. Make sure any local changes or commits are pushed, and that you have the latest main branch pulled.

Create a new feature branch, then oppen the file library/breeds/src/commonMain/kotlin/co/touchlab/gitportaltemplate/DatabaseHelper.kt.

This file is part of the linked KMP code. We can just edit it in place. We’ll make a small change, just to see how things work. Add a comment to the top of the DatabaseHelper class.

/**
 * Hello from the Android repo
 */
internal class DatabaseHelper(
// Etc

Add, commit, push, then create a PR in GitHub (the Android repo’s GitHub).

Pretend like you’ve gone through a PR process, then merge to main.

How are KMP changes shared?

On each push, GitPortal runs a GitHub Actions workflow. This process will check for changes to the KMP code, and if it finds any, they will be “pushed” to the KMP library’s repo.

If you’re working on the Android repo, that’s essentially it. Obviously, those changes will eventually need to wind up in the iOS repo, and that process involves some GitPortal-specific commands, but for day-to-day Android edits, you don’t really need to be aware of GitPortal at all.

Optional (but important) CI Change

Each time GitPortal’s CI check finds KMP changes, it pushes those changes to the KMP library, but it also adds a commit to the app repo. This commit updates GitPortal’s tracking config info.

By default, GitPortal’s CI check runs on each push to main. This is for easy initial config, and is necessary if you’re running in the unidirectional mode. However, it may not be what you want in practice for bidirectional.

If you plan on pulling multiple KMP changes from Android into iOS at a time (or vice-versa), you may want to change CI to be run explicitly. Say you want a few feature changes from Android to merge, then pull all of those KMP changes into iOS at once. You can reduce the extra GitPortal commits in Android by making this change.

In the app repo (Android, iOS, or both), open .github/workflows/check_gitportal_changes.yml. At the top, change the on: section to simply the following:

on: workflow_dispatch

# The rest...
jobs:
  gitportal_check_job:
    runs-on: ubuntu-latest
    concurrency:
# Etc...

When it’s time to “pull” changes into the other app, run the GitPortal CI action manually. It will grab all relevant commits since the last sync, and push them to the KMP library repo. It will still add a GitPortal commit to the app repo, but only one, rather than one for each.

Next - Part 5: Pulling Changes