· 6 min read Posted by Kevin Galligan
Part 5: Making KMP Changes with GitPortal
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
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.
Create a branch
It is highly suggested that you create a local branch to make KMP changes. It’ll be easier for reasons we’ll get into later.
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 -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 -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 -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 -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.
When we started making changes, I suggested creating a new branch in the Android repo. If you’ve also made changes to the Android app code that correspond to the KMP changes, you can just pull with GitPortal into that branch, and submit these changes to the Android repo directly. You can then do the same for iOS.
Using the unidirectional source model, this is a straightforward way to make app and KMP code changes together.
iOS
iOS is exactly the same. Cd to the local iOS folder, and run:
gitportal pull -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.
Bidirectional R&D program
We are running experiments with a few companies using a bidirectional model with GitPortal to get feedback and figure out the implementations necessary to make it work. If you’d like to try the bidirectional model with your team, [/contact-us](reach out).
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)