GitPortal for KMP Tutorial

For developers who aren’t editing KMP code directly and just consuming the KMP code in app repos, there are only a few things you’ll need to understand. The KMP code is already in the app repos, and it should be wired up to build automatically. You can edit the app code that calls the KMP code like you normally would.

Because this version of GitPortal is implementing a Unidirectional workflow, or “library dev”, the KMP code is “special”. You can build it locally, and even make local edits to help debug, but because the code only “moves” one way, you can’t commit and push changes to the KMP code.

The other operation developers may need to perform is updating to a new KMP library version.

We’ll demonstrate both of these operations in this section of the tutorial. We’ll only walk through changes in the Android app. The process and rules are the same for the iOS app.

Making changes

One of the core concepts of GitPortal is that you can add KMP source code to your app repos, but retain the same change and review process that you would normally use.

When using the unidirectional model, which we currently are, there’s only one rule: changes to the code linked KMP code, in our case the library folder, shouldn’t be committed and pushed directly to the Android repo.

Changes to the KMP library folder are only pulled from the KMP library repo.

To enable the unidirectional flow with source, we need to enforce the rule. Otherwise, KMP code changes in the library folder will wind up in the Android app, and that’s not what we want.

To enforce that changes to the library folder haven’t been made, GitPortal provides the check command.

Enforcing “the rules”

To locally see if you’ve committed any changes to the KMP library folder, run the GitPortal check command.

gitportal check library

Assuming you haven’t committed any local changes in the library folder, you’ll see the following output:

No changes found in module 'library'

Make a valid change

First lets make a change that doesn’t change the library code.

Open app/src/main/kotlin/co/touchlab/kampkit/android/MainApp.kt. Add a comment.

}

// The handle to the sdk, obviously... (I added this)
val sdkHandle = startSDK(analytics, this)
val koinApplication = startKoin {

Add and commit changes to git.

Now run the check:

gitportal check library

GitPortal will run its checks, then print out:

No changes found in module 'library'

That means everything is OK. Nothing has been changed in library. You push these changes to the Android remote repo without issue.

Make an invalid change

Obviously, having the KMP source readily available means it’s likely that changes will be committed to the KMP code, intentional or not.

Let’s add a println statement and “forget” to roll it back. Open library/breeds/src/commonMain/kotlin/co/touchlab/kmmbridgekickstart/DatabaseHelper.kt. Add the following at the top of the class:

    init {
        println("DatabaseHelper created")
    }

Add and commit this change to git.

Now, run check again:

gitportal check library

You’ll see the following printed by the terminal:

Changes found in module 'library'
Run the following from the project root to roll back changes
git apply --reverse --directory=library .git/tmp/ad551dac-3fec-48b1-8d11-2f8cb9c46699.diff
Failure (CheckDiffFound): Check Failed

In summary, that means you’ve committed changes to the library folder, which violates the rule.

This check will also be run by CI when you push, and will fail the build. You can see how that works by pushing your local changes to the Android repo and opening the “Actions” tab.

Fixing invalid changes

When you break the one rule and make changes to a KMP linked folder, you’ll need to roll them back.

It’s important to understand here, you do not need to roll back git history. GitPortal is looking for actual code changes, not git history. To fix these changes, simply undo the changes and commit again.

You can do this manually, or you can copy/paste the git apply line printed out by GitPortal. The check command writes out a git diff file with the changes that caused the issue. You can simply apply them in reverse.

In the app repo folder, from the check call above, simply run:

git apply --reverse --directory=library .git/tmp/ad551dac-3fec-48b1-8d11-2f8cb9c46699.diff

This will run those changes in reverse. These changes will be in your local folder, uncommitted. You can review them, then commit them.

If you run GitPortal check again:

gitportal check library

You should now see:

No changes found in module 'library'

You can not push your updates and the CI build should work without issue.

Pulling New Library Versions

When you publish new library versions to the KMP directory, pulling them into the app repos is easy.

Create a New KMP Version

First, we’ll need to make a change to the KMP repo, and create a new tag.

Open the local clone of your KMP repo with Android Studio or Intellij IDEA. We’ll make the same change from earlier again. Open breeds/src/commonMain/kotlin/co/touchlab/kmmbridgekickstart/DatabaseHelper.kt. Add the following at the top of the class:

    init {
        println("DatabaseHelper created (again)")
    }

In git, add, commit, and push these changes.

Now, add a version tag to the git repo. There are various ways to add a tag. Here, we’ll use terminal commands. From a terminal, cd to the KMP repo’s folder, and run the following:

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

This should create a new tag 0.1.1 and push it to the KMP repo remote. You can check if the tag exists by opening the GitHub page for the KMP repo in a browser and open “Releases” then click “Tags”.

Pull the new version to Android

In a terminal, cd to the Android repo folder. Run the following command:

gitportal pull library -t "0.1.1"

GitPortal will pull the relevant changes from the initial version, 0.1.0, and apply them to the local repo. It’ll also update the library/.gitportal metadata file with relevant values.

That’s it. Version update applied. If you commit and push to the Android repo, other devs will get these updates when they pull the Android repo.

Pull the new version to iOS

Same as Android. In a terminal, cd to the local iOS repo folder. Run the following:

gitportal pull library -t "0.1.1"

That’s it.

Next - Part 5: Making KMP Changes with GitPortal