Merge pull request #429 from splendo/release/0.2.2

Release/0.2.2

.github/pull_request_template.md

@@ -0,0 +1,3 @@
+<!-- fill in the issue number related to this pull request below -->
+
+#

DEVELOP.md

@@ -20,7 +20,7 @@ If a purely common test does not work, you can make the test's class `open` or `
 
 By extending `BaseTest` you can avoid a lot of boilerplate to make tests behave cross-platform (e.g. enableing the coroutines debugger).
 
-There are specialized test classes in the [`test-utils`](tree/master/test-utils) module, e.g. for testings `Flows`, `ViewModel`s etc. 
+There are specialized test classes in the [`test-utils`](test-utils/) module, e.g. for testings `Flows`, `ViewModel`s etc. 
 
 ### Android tests
 
@@ -39,32 +39,52 @@ Make sure you have the Simulator setup with a working target device. For now you
 
 The `ioTest` task supports the `--tests` flag like other Gradle tasks to filter which tests to run.
 
-Note that for kaluga iOS tests for kaluga run on a background thread, in order to have a properly working Main dispatchers (and align better with Android). How this works is descriped in [`test-utils`](tree/master/test-utils)
-
+Note that for kaluga iOS tests run on a background thread, in order to have a properly working Main dispatchers (and align better with Android). How this works is described in [`test-utils`](test-utils/)
 
 ## Architecture
 
 Most of the components within this project use Kotlin coroutines and `Flow`, so for new components try to use these APIs where it makes sense.
 
 For modules that rely on state, try using `StateRepo` based classes. These automatically expose a `Flow` for state changes, and using `ColdStateRepo` cold flow behaviour can be used.
 
+## Branching
+
+Kaluga uses [Gitflow](https://nvie.com/posts/a-successful-git-branching-model/).
+
+We use with the following branches:
+- `master`
+- `develop`
+- `release/*` (example: `release/0.1.2`)
+- `feature/[<issue_id>-]*` (example: `feature/345-bluetooth-scanning`)
+- `hotfix/[<issue_id>-]*` (example: `hotfix/678-navigation-crash`)
+
+When making a pull request fill in the template.
+
 ## Publishing
 
 ### Publishing process
 
-1. Bump version at `gradle/ext.gradle`:
+#### Version
+
+If you want to publish with a specific version string, you can override this value in `local.properties` (this file is already generated by your IDE normally), by setting `kaluga.libraryVersion`:
 
 ```sh
-library_version = 'X.X.X'
+kaluga.libraryVersion=0.1.0-special-build
 ```
 
-2. Publish to local maven:
+if this property is not set the version string is a combination of the version number, the current git branch (unless that branch is `master`, `main` or `develop`) and `-SNAPSHOT` (unless the `MAVEN_CENTRAL_RELEASE` environment variable is set to `true`). The exact implementation of this can be found in [gradle/gitBranch.gradle.kts](gradle/gitBranch.gradle.kts).
+
+For example if the version in `ext.gradle` is `1.1` and `feature/123_fix_bug` is the current branch the resulting version will be `1.1-feature-123_fix_bug-SNAPSHOT`.
+
+#### Publishing locally
+
+1. Publish to local maven:
 
 ```sh
 ./gradlew publishToMavenLocal
 ```
 
-3. Upload and publish on Maven Central:
+2. Upload and publish on Maven Central:
 
 ```sh
 ./gradlew publishAllPublicationsToSonatypeRepository -PsigningKeyId=SIGNING_KEY_ID -PsigningPassword=SIGNING_KEY_PASSWORD -PsigningSecretKeyRingFile=SIGNING_KEY_FILE -PossrhUsername=OSSRH_USERNAME -PossrhPassword=OSSRH_PASSWORD
@@ -76,6 +96,24 @@ Where `SIGNING_KEY_ID` is the key id associated with the signing key,
 `OSSRH_USERNAME` is the Sonatype user name to upload the repository to,
 and `OSSRH_PASSWORD` is the password for the Sonatype account to upload the repository to.
 
+If these values are present as environment variables they will also be picked up.
+
+#### Publishing via CI
+
+Bitrise automatically publishes every branch to the Sonatype snapshot repository (`https://oss.sonatype.org/content/repositories/snapshots/`). This is done using a (private) Bitrise project. A Maven Central release can be done by manually starting the `publisMavenCentralRelease` workflow for the appropriate release branch.
+
+#### Releasing to Maven Central
+
+Projects publishing to Sonatype's release repository need to be manually closed and released before they will appear on Maven Central. This can only be done by people with access.
+
+#### Increase version after publishing
+
+In case this has not been done yet, bump the version at [gradle/ext.gradle](gradle/ext.gradle) in the `develop` branch to start the next development iteration.
+
+```sh
+library_version = 'X.X.X'
+```
+
 ## Code conventions
 
 The project uses regular Kotlin code conventions. This includes not creating `com/splendo/kaluga` directories, since they are common to all other folders.
@@ -86,7 +124,9 @@ This project uses [ktlint](https://github.com/pinterest/ktlint) Kotlin linter wi
 Each component should setup ktlint gradle [plugin](https://github.com/jlleitschuh/ktlint-gradle) in `build.gradle.kts` file:
 
 ```kotlin
-apply(plugin = "org.jlleitschuh.gradle.ktlint")
+plugins {
+    id("org.jlleitschuh.gradle.ktlint")
+}
 ```
 
 You can run `Ktlint Check` configuration from IDE before commit changes to git.

README.md

@@ -75,16 +75,27 @@ Kaluga is available on Maven Central. For example the Kaluga Alerts can be impor
 
 ```kotlin
 repositories {
-    // ...
     mavenCentral()
 }
-// ...
 dependencies {
-    // ...
     implementation("com.splendo.kaluga:alerts:0.2.1")
 }
 ```
 
+You can also use the `SNAPSHOT` version based on the latest in the `develop` branch:
+
+```kotlin
+repositories {
+    maven("https://oss.sonatype.org/content/repositories/snapshots/")
+}
+dependencies {
+    implementation("com.splendo.kaluga:alerts:0.2.2-SNAPSHOT")
+}
+```
+
+**Please mind** that in order for kaluga to work properly on iOS it declares a [strict dependency](https://docs.gradle.org/7.0.2/userguide/rich_versions.html#sec:strict-version) on the [`native-mt` version of the `kotlinx.coroutines` library](https://github.com/Kotlin/kotlinx.coroutines/tree/287a931d3b8ce#native). If you want to use a different version make your own strict dependency declaration. This can be done simply by adding `!!`, for example: `implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.2-native-mt!!")`.
+
+
 To use kaluga with SwiftUI and/or Combine we have a [repo with Sourcery templates](https://github.com/splendo/kaluga-swiftui) to generate some Swift code to help get you started.
 
 ### Available Modules

adding-a-new-module/README.md

@@ -1,67 +1,62 @@
-## Template 
+## Template
 This **project** includes all common dependencies and settings for kaluga module.
 
 # Steps for adding a new module
-1. CopyPaste template module, select name for your module (we recommend to use only lowercase characters).
-2. `<your module>src/androidLibMain/AndroidManifest.xml` change `com.splendo.kaluga.template` to your module package name.	
-3. `<your module>src/androidLibAndroidTests/AndroidManifest.xml` change `com.splendo.kaluga.template` to your module package name.
-4. `<your module>src/androidLibAndroidTests/kotlin/TestActivity.kt` change package name from `com.splendo.kaluga.template` to `com.splendo.kaluga.your module`.
-5. Include your module to kaluga project
-	go to `kaluga/settings.gradle/kts`
-	And add in the end of the file:
-	`include(":<your module>")`.
-6. Add Unit tests
+1. Run gradle task: `./gradlew createNewModule -P module_name=<your-module>` from the root directory.
+1. Include your module to kaluga project edit `kaluga/settings.gradle.kts` by adding: `include(":<your-module>")`.
+1. Add Unit tests
     * [Common Unit Tests](#commonTests)
     * [iOS Unit Tests](#iosTests)
     * [Android Unit Tests](#androidLibTests)
-7. [Add Android Instrumented Unit Tests](#instrumentedUnitTests)
-8. Add your source code
+1. [Add Android Instrumented Unit Tests](#instrumentedUnitTests)
+1. Add your source code
     * <a name="commonMain-sources"></a>**commonMain** - non-platform-specific implementation and `expect` declaration.
     * <a name="iosMain-sources"></a>**iosMain** - iOS specific implementation.
     * <a name="androidLibMain-sources"></a>**androidLibMain** - Android specific implementation.
     * <a name="jvmMain-sources"></a>**jvmMain** - jvm specific implementation.
     * <a name="jsMain-sources"></a>**jvmMain** - js specific implementation.
-8. Remove template README files from your module when you don't need them anymore.
-9. Don't forget to update copyright if files were imported from another project. To do that use **Code > Update Copyright...**.
-10. Add documentation to your code if needed.
-11. Add an example of usage to the example project.
+1. Don't forget to update copyright if files were imported from another project. To do that use **Code > Update Copyright...**.
+1. Add documentation to your code if needed.
+1. Add an example of usage to the example project.
 
 ---
-### <a name="commonTests"></a> Common Unit Tests 
+
+### <a name="commonTests"></a> Common Unit Tests
 
 To run all common tests:
 1. Run > Edit Configurations. The Run/Debug Configurations dialog appears.
-2. Press "+" button and select "Gradle".
-3. In the right part of dialog enter name.
-4. Fill in the Gradle project field (kaluga:<your module>).
-5. In a field "Tasks" enter cleanAllTests allTests.
-6. Press "Ok" or "Apply". Now you can choose and run configuration.
+1. Press "+" button and select "Gradle".
+1. In the right part of dialog enter name.
+1. Fill in the Gradle project field (kaluga:<your-module>).
+1. In a field "Tasks" enter cleanAllTests allTests.
+1. Press "Ok" or "Apply". Now you can choose and run configuration.
 
-Please note that this scheme will run all gradle test tasks including iOS. Use [test filtering](https://docs.gradle.org/current/userguide/java_testing.html#test_filtering) if you want to run some specific tests.   
+Please note that this scheme will run all gradle test tasks including iOS. Use [test filtering](https://docs.gradle.org/current/userguide/java_testing.html#test_filtering) if you want to run some specific tests.
 Use cleanJvmTest jvmTest if you want to run only JVM tests.
 
 ----
+
 ### <a name="iosTests"></a> iOS Unit Tests
 
 To run all common tests:
 1. Run > Edit Configurations. The Run/Debug Configurations dialog appears.
-2. Press "+" button and select "Gradle".
-3. In the right part of dialog enter name.
-4. Fill in the Gradle project field (kaluga:<your module>).
-5. In a field "Tasks" enter cleanIosx64Test iosx64Test.
-6. Press "Ok" or "Apply". Now you can choose and run configuration.
+1. Press "+" button and select "Gradle".
+1. In the right part of dialog enter name.
+1. Fill in the Gradle project field (kaluga:<your module>).
+1. In a field "Tasks" enter cleanIosx64Test iosx64Test.
+1. Press "Ok" or "Apply". Now you can choose and run configuration.
 
-Use [test filtering](https://docs.gradle.org/current/userguide/java_testing.html#test_filtering) if you want to run some specific tests.   
-
+Use [test filtering](https://docs.gradle.org/current/userguide/java_testing.html#test_filtering) if you want to run some specific tests.
 
 ----
-### <a name="androidLibTests"></a> Add Android Unit Tests 
+
+### <a name="androidLibTests"></a> Add Android Unit Tests
 
 Unit tests which can run without a device.
 
 Example:
-```kotlin
 
+```kotlin
 class ExampleTest {
 
     val instance = ExampleClass()
@@ -71,23 +66,25 @@ class ExampleTest {
         assertNotNull(instance.someProperty)
     }
 }
-
 ```
 
 To run all android unit tests:
 1. Run > Edit Configurations. The Run/Debug Configurations dialog appears.
-2. Press "+" button and select "Android JUnit".
-3. In the right part of dialog enter name.
-4. For "Test kind" select "All in package".
-5. Enter your package name (com.splendo.kaluga.<your package name>)
-6. For "Use class path of module" select your module.
-7. Press "Ok" or "Apply". Now you can choose and run configuration.
+1. Press "+" button and select "Android JUnit".
+1. In the right part of dialog enter name.
+1. For "Test kind" select "All in package".
+1. Enter your package name (com.splendo.kaluga.<your-module>)
+1. For "Use class path of module" select your module.
+1. Press "OK" or "Apply". Now you can choose and run configuration.
 
 ----
-### <a name="instrumentedUnitTests"></a> Add Android Instrumented Unit Tests 
+
+### <a name="instrumentedUnitTests"></a> Add Android Instrumented Unit Tests
+
 Add unit tests which should run on a device or emulator
 
 Example:
+
 ```kotlin
 const val DEFAULT_TIMEOUT = 2_500L
 
@@ -107,6 +104,6 @@ class ExampleInstrumentedTest {
 
 To run all instrumented unit tests
 1. Run > Edit Configurations. The Run/Debug Configurations dialog appears.
-2. Press "+" button and select "Android Instrumented Tests".
-3. In the right part of dialog enter name and select your module.
-4. Press "Ok" or "Apply". Now you can choose and run configuration.
+1. Press "+" button and select "Android Instrumented Tests".
+1. In the right part of dialog enter name and select your module.
+1. Press "OK" or "Apply". Now you can choose and run configuration.

adding-a-new-module/template/build.gradle.kts

@@ -22,9 +22,14 @@ dependencies {
 
 kotlin {
     sourceSets {
-        getByName("commonMain") {
+        commonMain {
             dependencies {
-                implementation(project(":base", ""))
+                implementation(project(":base"))
+            }
+        }
+        commonTest {
+            dependencies {
+                implementation(project(":test-utils"))
             }
         }
     }

adding-a-new-module/template/src/androidLibAndroidTest/AndroidManifest.xml

@@ -1,4 +1,4 @@
-<manifest package="com.splendo.kaluga.template"
+<manifest package="com.splendo.kaluga.%MODULE%"
           xmlns:android="http://schemas.android.com/apk/res/android">
     <application android:theme="@style/Theme.AppCompat">
         <activity android:name=".TestActivity"/>

adding-a-new-module/template/src/androidLibAndroidTest/kotlin/TestActivity.kt

@@ -1,25 +1,23 @@
 /*
+ Copyright %YEAR% Splendo Consulting B.V. The Netherlands
 
-Copyright 2019 Splendo Consulting B.V. The Netherlands
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+      http://www.apache.org/licenses/LICENSE-2.0
 
-     http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
 
 */
 
-package com.splendo.kaluga.template
+package com.splendo.kaluga.%MODULE%
 
 import android.os.Bundle
 import androidx.appcompat.app.AppCompatActivity
 
-class TestActivity : AppCompatActivity() {
-}
+class TestActivity : AppCompatActivity()

adding-a-new-module/template/src/androidLibMain/AndroidManifest.xml

@@ -1,3 +1,2 @@
-<manifest package="com.splendo.kaluga.template"
-          xmlns:android="http://schemas.android.com/apk/res/android"
-/>
+<manifest package="com.splendo.kaluga.%MODULE%"
+          xmlns:android="http://schemas.android.com/apk/res/android" />

alerts/build.gradle.kts

@@ -22,6 +22,10 @@ dependencies {
 }
 
 kotlin {
+    js {
+        nodejs()
+    }
+
     sourceSets {
         getByName("commonMain") {
             dependencies {