diff --git a/documentation/_data/project.yml b/documentation/_data/project.yml index dd146f7..14285e4 100644 --- a/documentation/_data/project.yml +++ b/documentation/_data/project.yml @@ -23,10 +23,10 @@ library: # optional dependencies: compose: - cmp: 1.7.1 - compose: 1.7.1 + cmp: 1.7.3 + compose: 1.7.5 material3: 1.3.1 - experimental: true + experimental: false # ------------- # Module @@ -40,9 +40,6 @@ groups: - name: modules label: Modules gradle-comment: statesaver modules - - name: plugins - label: Plugins - gradle-comment: gradle plugins modules: - name: core @@ -55,26 +52,26 @@ modules: jvm: false info: dependencies: [] - - name: statesaver-kotpreferences + - name: statesaver-preferences group: modules - description: a statesaver implementation for kotpreferences + description: saves the state of the last shown changelog inside a preference file optional: true platforms: android: true ios: true jvm: false info: - dependencies: - - name: KotPreferences - link: https://github.com/MFlisar/KotPreferences - version: 0.7.2 - - name: statesaver-preferences + dependencies: [ ] + - name: statesaver-kotpreferences group: modules - description: a statesaver implementation for jetpack preferences + description: saves the state of the last shown changelog inside a preference file using my KotPreferences library optional: true platforms: android: true ios: true jvm: false info: - dependencies: [] \ No newline at end of file + dependencies: + - name: KotPreferences + link: https://github.com/MFlisar/KotPreferences + version: 0.7.2 \ No newline at end of file diff --git a/documentation/docs/advanced/gradle-plugin.md b/documentation/docs/advanced/gradle-plugin.md new file mode 100644 index 0000000..0ef8ffa --- /dev/null +++ b/documentation/docs/advanced/gradle-plugin.md @@ -0,0 +1,57 @@ +--- +icon: material/button-pointer +--- + +This plugin allows you to transform a version string into a version code. This is useful if you want to use a version string in your gradle files and want to calculate the version code based on it. + +#### Example + +Top level `build.gradle.kts` file: + +```kotlin +plugins { + id("io.github.mflisar.composechangelog.gradle-plugin") apply false +} +``` + +After adding above you can simple apply the plugin inside your apps `build.gradle.kts` file like following and use it like following: + +```kotlin +import com.michaelflisar.composechangelog.Changelog +import com.michaelflisar.composechangelog.DefaultVersionFormatter + +plugins { + // other plugins + id("com.android.application") + id("kotlin-android") + id("kotlin-kapt") + + // plugin of compose changelog + id("io.github.mflisar.composechangelog.gradle-plugin") +} + +// define your app version code based on your format, here we use the Major.Minor.Patch format +val version = "0.3.0" +val code = Changelog.buildVersionCode(version, DefaultVersionFormatter(DefaultVersionFormatter.Format.MajorMinorPatch)) + +// make sure to use the SAME formatter inside your code whenever you want to show a changelog - Major.Minor.Patch format is the default one though + +android { + + // ... + + defaultConfig { + // use the version and code variables from above + versionCode = code + versionName = version + } + + // ... +} +``` + +You now only must change `val version = "0.3.0"` to whatever new version you want and the code will be calculated by itself. + +Additionally you can easily use the `versionName` tag inside your `changelog.xml` file, the formatter will correctly parse it to it's number for you. + +**Always make sure to use the same formatter in your `build.gradle.kts` as well as inside your code.** \ No newline at end of file diff --git a/documentation/docs/index.md b/documentation/docs/index.md index 7373a86..5105937 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -8,11 +8,21 @@ icon: material/information-variant {% include 'region-features.md' %} -!!! info +* filtering + * useful to filter out uninteresting old changelog entries on app start + * useful for filtering changelog based on build flavour +* also supports automatic handling of showing changelogs on app start (uses preference to save last seen changelog version and handles everything for you automatically to only show **new changelogs** and only show those once) +* customise look + * you can provide custom composables for every item type if desired + * you can provide custom version name formatter + * you can provide a custom sorter +* supports raw and xml resources, default resource name is `changelog.xml` in raw folder +* supports summaries with a "show more" button +* optional provides a `gradle plugin` that allows you to convert version names automatically to version numbers - This docs are not written yet - the docs are still placed in the github readme [here](https://github.com/MFlisar/ComposeChangelog) for now. +!!! info -Under Development + All features are splitted into separate modules, just include the modules you want to use! {% include 'screenshots.md' %} diff --git a/documentation/docs/modules/core.md b/documentation/docs/modules/core.md new file mode 100644 index 0000000..2e68c3d --- /dev/null +++ b/documentation/docs/modules/core.md @@ -0,0 +1,7 @@ +--- +icon: material/puzzle +--- + +This is the core module. It contains the changelog composable and all the necessary logic. + +All other modules are just optional extensions. \ No newline at end of file diff --git a/documentation/docs/modules/statesaver-kotpreferences.md b/documentation/docs/modules/statesaver-kotpreferences.md new file mode 100644 index 0000000..78f0ee3 --- /dev/null +++ b/documentation/docs/modules/statesaver-kotpreferences.md @@ -0,0 +1,11 @@ +--- +icon: material/puzzle +--- + +This module provides the functionality to save and use the last show changelog version. It uses my `KotPreferences` library for this purpose. + +```kotlin +val changelogStateSaverKotPrefs = ChangelogStateSaverKotPreferences(DemoPrefs.lastShownVersionForChangelog) // pass in any StorageSetting from KotPreferences + +// use this state saver with ComposeChangelog +``` \ No newline at end of file diff --git a/documentation/docs/modules/statesaver-preferences.md b/documentation/docs/modules/statesaver-preferences.md new file mode 100644 index 0000000..99c42fc --- /dev/null +++ b/documentation/docs/modules/statesaver-preferences.md @@ -0,0 +1,11 @@ +--- +icon: material/puzzle +--- + +This module provides the functionality to save and use the last show changelog version. It uses the plain jetpack preferences to store the version code of the last shown changelog. + +```kotlin +val changelogStateSaverKotPrefs = ChangelogStateSaverPreferences.create(context) + +// use this state saver with ComposeChangelog +``` \ No newline at end of file diff --git a/documentation/docs/usage.md b/documentation/docs/usage.md index a013a5b..8354bd8 100644 --- a/documentation/docs/usage.md +++ b/documentation/docs/usage.md @@ -2,4 +2,106 @@ icon: material/keyboard --- -#### TODO \ No newline at end of file +#### Define your changelog as xml file (on android, a raw xml is preferred!) + +```xml + + + + + -new gradle plugin added - you don't need to convert version names to version codes anymore! + + + Some info 1 - apostrophe test: it's weird, but apostrophes do not work in precompiled xml files placed in xml resources! + Some improvement 1 + Some bugfix 1 + Some info 2 + Some improvement 2 + Some bugfix 2 + Some info 3 + Some improvement 3 + Some bugfix 3 + My custom tag text... + + + + + This version has a summary item only - no show more button will be shown even if show more buttons are enabled + + + Some info + Some improvement + Some bugfix + + + Some dogs info - filter only set in release tag + Some dogs improvement - filter only set in release tag + Some dogs bugfix - filter only set in release tag + + + single summary of version 1.05 + Some cats info - filter only set in release tag + Some cats improvement - filter only set in release tag + Some cats bugfix - filter only set in release tag + + + single cats summary of version 1.00 + single dogs summary of version 1.00 + New cats added - this info has filter text 'cats' + New dogs added - this info has filter text 'dogs' + Some cats improvement - this info has filter text 'cats' + Some dogs improvement - this info has filter text 'dogs' + Some cats bugfix - this info has filter text 'cats' + Some dogs bugfix - this info has filter text 'dogs' + + + this release does not have any summary item and will be shown expanded even if summary is enabled - this behaviour can be adjusted by the second parameter in the builder with which you enable summaries + + +``` + +#### Show the interesting parts of the changelog on app start + +```kotlin + // 1) we need a state saver to persist the version for which the changelog was last shown +// use either of the following 2 or implement the corresponding interface yourself + +// saves the last shown version inside a preference file +val changelogStateSaver = remember { + ChangelogStateSaverPreferences.create(context) +} + +// ALTERNATIVE: if you use my kotpreference library like this demo you can do following: +val changelogStateSaverKotPrefs = remember { + ChangelogStateSaverKotPreferences(DemoPrefs.lastShownVersionForChangelog) +} + +// 2) optional - here you can apply some customisations like changelog resource id, localized texts, styles, filter, sorter, renderer... +val setup = ChangelogDefaults.setup() + +// 3) show the changelog for the app start - this will only show the changelogs that the user did not see yet +val versionName = ChangelogUtil.getAppVersionName(context) +ShowChangelogDialogIfNecessary(changelogStateSaver, versionName, setup) +``` + +#### Show the full changelog + +```kotlin +// 1) we need a state to decide if we need to show the changelog or not +var showChangelog by remember { mutableStateOf(false) } + +// 2) we need some event source +Button(onClick = { showChangelog = true }) { + Text("Show Changelog") +} + +// 3) we show the changelog if necessary +if (showChangelog) { + // optional setup... + val setup = ChangelogDefaults.setup() + ShowChangelogDialog(setup) { + // this is the dismiss callback, here we must reset the showChangelog flag + showChangelog = false + } +} +``` \ No newline at end of file diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index dbaaa37..0161a80 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -124,26 +124,12 @@ nav: - Dependencies: dependencies.md - Setup: setup.md - Usage: usage.md - #- Modules: - # - Core: modules/core.md - # - Dialog Info: modules/dialog-info.md - # - Dialog Input: modules/dialog-input.md - # - Dialog Number: modules/dialog-number.md - # - Dialog Date: modules/dialog-date.md - # - Dialog Time: modules/dialog-time.md - # - Dialog Color: modules/dialog-color.md - # - Dialog List: modules/dialog-list.md - # - Dialog Menu: modules/dialog-menu.md - # - Dialog Progress: modules/dialog-progress.md - # - Dialog Billing: modules/dialog-billing.md - #- Advanced: - # - Dialog Styles: advanced/styles.md - # - Events: advanced/events.md - # - Buttons: advanced/buttons.md - # - Options: advanced/options.md - # - Custom Dialog: advanced/custom-dialog.md - #- Migration: - # - Version 2: migration/v2.md + - Modules: + - Core: modules/core.md + - State Saver Preferences: modules/statesaver-preferences.md + - State Saver KotPreferences: modules/statesaver-kotpreferences.md + - Advanced: + - Gradle Plugin: advanced/gradle-plugin.md - More: - Other Libraries: other-libraries.md - About Me: me.md diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 634d344..5c38f09 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -4,7 +4,7 @@ gradle = "8.7.3" kotlin = "2.1.0" dokka = "1.9.20" gradle-maven-publish-plugin = "0.30.0" -compose = "1.7.1" +compose = "1.7.3" [plugins] diff --git a/library/core/build.gradle.kts b/library/core/build.gradle.kts index be45c50..17edd6d 100644 --- a/library/core/build.gradle.kts +++ b/library/core/build.gradle.kts @@ -1,7 +1,6 @@ import com.vanniktech.maven.publish.JavadocJar import com.vanniktech.maven.publish.KotlinMultiplatform import com.vanniktech.maven.publish.SonatypeHost -import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi import org.jetbrains.kotlin.gradle.dsl.JvmTarget plugins { @@ -43,7 +42,6 @@ kotlin { // Android androidTarget { publishLibraryVariants("release") - @OptIn(ExperimentalKotlinGradlePluginApi::class) compilerOptions { jvmTarget.set(JvmTarget.JVM_17) } diff --git a/library/modules/statesaver/kotpreferences/build.gradle.kts b/library/modules/statesaver/kotpreferences/build.gradle.kts index c0a1df8..336f593 100644 --- a/library/modules/statesaver/kotpreferences/build.gradle.kts +++ b/library/modules/statesaver/kotpreferences/build.gradle.kts @@ -1,7 +1,6 @@ import com.vanniktech.maven.publish.JavadocJar import com.vanniktech.maven.publish.KotlinMultiplatform import com.vanniktech.maven.publish.SonatypeHost -import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi import org.jetbrains.kotlin.gradle.dsl.JvmTarget plugins { @@ -41,7 +40,6 @@ kotlin { // Android androidTarget { publishLibraryVariants("release") - @OptIn(ExperimentalKotlinGradlePluginApi::class) compilerOptions { jvmTarget.set(JvmTarget.JVM_17) } diff --git a/library/modules/statesaver/preferences/build.gradle.kts b/library/modules/statesaver/preferences/build.gradle.kts index 4de357b..4938b85 100644 --- a/library/modules/statesaver/preferences/build.gradle.kts +++ b/library/modules/statesaver/preferences/build.gradle.kts @@ -1,7 +1,6 @@ import com.vanniktech.maven.publish.JavadocJar import com.vanniktech.maven.publish.KotlinMultiplatform import com.vanniktech.maven.publish.SonatypeHost -import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi import org.jetbrains.kotlin.gradle.dsl.JvmTarget plugins { @@ -41,7 +40,6 @@ kotlin { // Android androidTarget { publishLibraryVariants("release") - @OptIn(ExperimentalKotlinGradlePluginApi::class) compilerOptions { jvmTarget.set(JvmTarget.JVM_17) }