· 6 min read Posted by Kevin Galligan
Part 4: GitPortal App Developer Workflow
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.
This restriction may seem odd if you haven’t read the KMP For Teams documentation. If not, I’d strongly encourage you to take a look before continuing. If you’re in the KotlinConf code lab, don’t worry. We’ll explain it.
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 checkAssuming you haven’t committed any local changes in the library folder, you’ll see the following output:
No changes found in module 'library'All GitPortal operations will return an error if you have any uncommitted changes to your repo. Make sure you commit before you run anything.
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 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 checkYou’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 FailedIn 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.diffThis 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 checkYou should now see:
No changes found in module 'library'You can now push your updates and the CI build should work without issue.
Your IDE may have auto-formatting turned on. This may cause your code to change when browsing it. Future versions of GitPortal may be smart enough to ignore insignificant changes, but for now, it’s a strict git diff.
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.
GitPortal provides a way to do this directly from the app repos, but we’ll be covering that in the next section. For now, we’ll make these changes directly.
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 --tagsThis 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 -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.
If your updated version has a different commit history compared to the previous version, you’ll need to add the force tag -f. GitPortal will tell you this if you need to do it. The force pull only grabs the diff changes, not the full history. We may apply force on pull statements by default in the future, as there’s no major downside to using force pull. For now, however, you’ll need to add the force tag manually.
Pull the new version to iOS
Same as Android. In a terminal, cd to the local iOS repo folder. Run the following:
gitportal pull -t "0.1.1"That’s it.