GitPortal for KMP Tutorial

You can push changes directly the KMP repo, but generally speaking, making changes directly in the app repos is easier. GitPortal has a workflow for local changes.

Setup

If you’ve gone through the full tutorial, you’ll have local clones of your Android and iOS repos, with the linked KMP library be at version 0.1.1. You can check the status of your app repos by running the GitPortal status command.

In a terminal, cd to your local Android app repo, and run:

gitportal status library

You’ll see the following:

Remote: https://github.com/[your org]/GitPortalTemplateLibrary.git
From tag: 0.1.1

Make KMP Changes

The unidirectional code flow model doesn’t allow direct changes to the KMP code from app repos. However, you can make KMP changes in your app repo, and push them to the KMP repo directly.

Doing this will put your local app repo in a special GitPortal state.

In the Android repo, creat a branch kmpchanges.

In Android Studio or Intillij, open the project, and make some KMP code changes. Let’s open our old friend library/breeds/src/commonMain/kotlin/co/touchlab/kmmbridgekickstart/DatabaseHelper.kt. Edit the init statement we added previously.

    init {
        println("DatabaseHelper created (app KMP changes)")
    }

In git, add and commit these changes.

Use GitPortal to push changes

GitPortal has a push command that collects the KMP changes and pushes them to the KMP repo. You’ll need to provide a branch to push them to in the KMP repo.

gitportal push library -b mykmpchanges

Look at the changes

Open your browser to the GitHub repo for your KMP library. You should see the branch mykmpchanges. If you open the history, you’ll see the commit GitPortal created with your KMP changes.

Any changes you may have made in the Android repo that weren’t in the library folder will be ignored by GitPortal when pushing.

You are now in the “editing” state

Locally, the push operation changes the library/.gitportal metadata file. It updates some tracking info, but it also removes the pullTag attribute. The pullTag attribute tells GitPortal what tag the local folder is attached to. When it’s gone, this means we’re in the “editing” state, and GitPortal check calls will fail.

Why? GitPortal is implementing the unidirectional model. In the current state, you have changes specific to your recent push. Those changes need to be reviewed and merged into the KMP repo, and a new version tag needs to be created. To get your local Android app into the “normal” state, you’ll need to pull a new version tag.

Just FYI, when in the “editing” state, if you push your Android code to the Android remote repo, the CI check will also fail.

Review/edit changes in the iOS repo

You can pull KMP repos from a branch into a local app repo. This will put that repo into the “editing” state as well, but it’ll allow you to review and edit those changes for the “other” platform.

In a terminal, cd to the iOS repo folder, and run:

gitportal pull library -b mykmpchanges

Assuming this succeeds, you can make further KMP edits, to fix and/or implement the iOS side of your changes. When done, add and commit with git, then push further changes again.

Run the same GitPortal push command again:

gitportal push library -b mykmpchanges

This call will push any local KMP changes you might have made.

Merge and tag changes in the KMP repo

In the KMP repo, merge the changes from the mykmpchanges branch. You can follow whatever PR and review process you’d like.

Make another version tag. In a terminal, cd to the KMP repo folder and run:

git tag -a "0.1.2" -m "Version 0.1.2"
git push origin --tags

You now have a version 0.1.2 in your KMP repo.

Pull the new version into the app repos

Android

To update the Android app, cd into the local Android folder and run:

gitportal pull library -t "0.1.2"

Assuming no issues or conflicts, this will pull any changes from 0.1.2 and apply them. Your repo will now be out of the “editing” state.

iOS

iOS is exactly the same. Cd to the local iOS folder, and run:

gitportal pull library -t "0.1.2"

Push to the iOS repo. That’s it.

What’s next?

This is how GitPortal implements a unidirectional code flow model. For “library dev”, this model is OK. However, you’ll probably find it to be frustrating and slow. Certainly if you want to scale your KMP code usage, this model won’t work. Changes involve a lot of process, and have linear versions. Multiple devs making concurrent changes really won’t work well.

Read our KMP For Teams Guide

If you haven’t yet, make sure to read through the KMP For Teams Guide. It explains the concepts behind GitPortal’s unidirectional model, and various approaches to scaling your KMP adoption.

Bidirectional Code Flow Model

A new model presenting in the KMP For Teams Guide is the bidirectional code flow model. Most teams assume that to “scale” KMP, you’ll need to merge your app code and KMP code into a single repo. The “monorepo” model. While this may be the approach you take, it introduces its own issues.

We’re working on implementing a bidirectional model with GitRepo. The git tooling is more complex to implement because of potentially conflicting changes in the KMP repo. Also, implementing every possible feature would be very difficult, and probably not very useful. We are starting with several constraints, and adding features as teams need them.

The bidirectional model is conceptually simple. Instead of pulling KMP changes from your KMP repo into your app repos, the changes go in the other direction. You make changes to both your app code and the KMP code, in the app repo directly. Those changes are pushed to your app repo directly, and when merged, CI moves any potential KMP changes to the shared repo automatically.

KMP changes are managed in the KMP repo through some “git magic”. I won’t go into the details now. In summary, KMP changes from one repo are pulled into the other app repo and merged.

The benefits are simple:

• The apps can be developed independently
• KMP changes won’t “break” the other app unintentionally
• Bonus: you don’t need the hassle and risk of moving to a monorepo. Applying the bidirectional flow is a config change (as is reverting it)