diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9aa90d2b..e2194a8c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,101 @@ # Contributing -## Creating issues +## Find or file an issue to work on -If you notice a discrepancy between PokeAPI's responses and PokeKotlin's object -models, you should create an issue and I'll fix it as soon as possible. You can -also post questions, feature suggestions, general support issues, or anything -else. +If you're looking to add a feature or fix a bug and there's no issue filed yet, +it's good to +[file an issue](https://github.com/pokeapi/pokekotlin/issues/new/choose) first +to have a discussion about the change before you start working on it. -## Submitting changes +If you're new and looking for things to contribute, see our +[good first issue](https://github.com/pokeapi/pokekotlin/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) +label. These issues are usually ready to work on and don't require deep +knowledge of the library's internals. -Remember to always work in a separate branch, use descriptive commit messages, -and use pull requests to submit your changes. Always create an issue and mention -you're working on something first. Also, make sure that all tests pass. If you -add new fields or types, write the tests to check them against PokeAPI. +## Development Environment Setup + +### Prerequisites + +1. **IDE**: [IntelliJ IDEA](https://www.jetbrains.com/idea/) is recommended. + VSCode and other editors won't work well, as this is a Kotlin project and + there's not yet a stable LSP for Kotlin. +2. **Node.js**: Required for running the test server. Instructions can be found + at [nodejs.org](https://nodejs.org/en/download). +3. **Just** (optional): A command runner that simplifies running common tasks. + Installation instructions can be found at + [just.systems](https://just.systems/man/en/). + +### Cloning the Repository + +This repository uses a Git submodule for test data. When cloning, make sure to +include the `--recurse-submodules` flag: + +```bash +git clone --recurse-submodules 'https://github.com/PokeAPI/pokekotlin.git' +``` + +If you've already cloned the repository without submodules, you can initialize +them with: + +```bash +git submodule update --init --recursive +``` + +### IDE Setup + +1. Open the project in IntelliJ IDEA or similar IDE. +2. Make sure you have the Kotlin Multiplatform plugin installed. This should be + included by default in recent versions of IntelliJ IDEA and Android Studio. +3. For more information on setting up Kotlin Multiplatform, refer to the + [official Kotlin Multiplatform documentation](https://kotlinlang.org/docs/multiplatform-get-started.html). + +## Running Tests + +Most tests in this project rely on a local server that serves the PokeAPI data +from static files. The server needs to be running before executing the tests. + +### Starting the Test Server + +You can start the test server using the provided script: + +```bash +./scripts/test-server +``` + +Or if you have Just installed, you can use: + +```bash +just test-server +``` + +### Running Tests + +The project includes tests for various platforms. You can run them using Gradle +directly or through the Just commands. For details on available commands, see +the [`justfile`](./justfile) in the project root or run: + +```bash +just +``` + +## Code Formatting + +The project uses Spotless for code formatting. You can apply the formatting +rules with: + +```bash +just format +``` + +Or using Gradle directly: + +```bash +./gradlew spotlessApply +``` + +If you'd prefer to apply automatically on commit, opt in to the pre-commit hook +with: + +```bash +./gradlew installGitHooks +``` diff --git a/gradle.properties b/gradle.properties index 81ba6736..06a6e625 100644 --- a/gradle.properties +++ b/gradle.properties @@ -9,4 +9,3 @@ org.gradle.configuration-cache=false org.gradle.jvmargs=-Xmx4096M -Dfile.encoding=UTF-8 android.nonTransitiveRClass=true android.useAndroidX=true -android.experimental.lint.version=8.8.2 diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 1ee081db..4ec71da8 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -1,21 +1,25 @@ [versions] androidx-activity = "1.10.1" -androidx-navigation = "2.9.0-beta02" +androidx-navigation = "2.9.0-beta03" kotlinx-coroutines = "1.10.2" -kotlinx-io = "0.7.0" +kotlinx-io = "0.8.0" kotlinx-serialization = "1.8.1" -ktor = "3.1.3" +ktor = "3.2.0" -gradle-android = "8.7.2" -gradle-compose = "1.8.1" -gradle-kotlin = "2.1.21" +# Upgrade these in sync, also Gradle and JDK +gradle-kotlin = "2.2.0" +gradle-android = "8.10.0" +gradle-suspendTransformCompiler = "2.2.0-0.13.1" + +gradle-compose = "1.8.2" gradle-dokka = "2.0.0" gradle-jgitver = "0.10.0-rc03" -gradle-mavenPublish = "0.32.0" +gradle-mavenPublish = "0.33.0" gradle-mkdocs = "4.0.1" gradle-spotless = "7.0.4" -gradle-suspendTransformCompiler = "2.1.20-0.12.0" -tool-prettier = "3.5.3" +tool-prettier = "3.6.2" + +# Don't forget to check settings.gradle for more versions [libraries] androidx-activity-compose = { module = "androidx.activity:activity-compose", version.ref = "androidx-activity" } diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar index 490fda85..1b33c55b 100644 Binary files a/gradle/wrapper/gradle-wrapper.jar and b/gradle/wrapper/gradle-wrapper.jar differ diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index e18bc253..ff23a68d 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,6 +1,6 @@ distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-8.12.1-bin.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.2-bin.zip networkTimeout=10000 validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME diff --git a/gradlew b/gradlew index 1aa94a42..23d15a93 100755 --- a/gradlew +++ b/gradlew @@ -15,6 +15,8 @@ # See the License for the specific language governing permissions and # limitations under the License. # +# SPDX-License-Identifier: Apache-2.0 +# ############################################################################## # @@ -55,7 +57,7 @@ # Darwin, MinGW, and NonStop. # # (3) This script is generated from the Groovy template -# https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt +# https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt # within the Gradle project. # # You can find Gradle at https://github.com/gradle/gradle/. @@ -84,7 +86,7 @@ done # shellcheck disable=SC2034 APP_BASE_NAME=${0##*/} # Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036) -APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit +APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit # Use the maximum available, or set MAX_FD != -1 to use that value. MAX_FD=maximum @@ -112,7 +114,7 @@ case "$( uname )" in #( NONSTOP* ) nonstop=true ;; esac -CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar +CLASSPATH="\\\"\\\"" # Determine the Java command to use to start the JVM. @@ -203,7 +205,7 @@ fi DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' # Collect all arguments for the java command: -# * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments, +# * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments, # and any embedded shellness will be escaped. # * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be # treated as '${Hostname}' itself on the command line. @@ -211,7 +213,7 @@ DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' set -- \ "-Dorg.gradle.appname=$APP_BASE_NAME" \ -classpath "$CLASSPATH" \ - org.gradle.wrapper.GradleWrapperMain \ + -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \ "$@" # Stop when "xargs" is not available. diff --git a/gradlew.bat b/gradlew.bat index 93e3f59f..db3a6ac2 100644 --- a/gradlew.bat +++ b/gradlew.bat @@ -13,6 +13,8 @@ @rem See the License for the specific language governing permissions and @rem limitations under the License. @rem +@rem SPDX-License-Identifier: Apache-2.0 +@rem @if "%DEBUG%"=="" @echo off @rem ########################################################################## @@ -43,11 +45,11 @@ set JAVA_EXE=java.exe %JAVA_EXE% -version >NUL 2>&1 if %ERRORLEVEL% equ 0 goto execute -echo. -echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. -echo. -echo Please set the JAVA_HOME variable in your environment to match the -echo location of your Java installation. +echo. 1>&2 +echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2 +echo. 1>&2 +echo Please set the JAVA_HOME variable in your environment to match the 1>&2 +echo location of your Java installation. 1>&2 goto fail @@ -57,22 +59,22 @@ set JAVA_EXE=%JAVA_HOME%/bin/java.exe if exist "%JAVA_EXE%" goto execute -echo. -echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% -echo. -echo Please set the JAVA_HOME variable in your environment to match the -echo location of your Java installation. +echo. 1>&2 +echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2 +echo. 1>&2 +echo Please set the JAVA_HOME variable in your environment to match the 1>&2 +echo location of your Java installation. 1>&2 goto fail :execute @rem Setup the command line -set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar +set CLASSPATH= @rem Execute Gradle -"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %* +"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %* :end @rem End local scope for the variables with windows NT shell diff --git a/justfile b/justfile index 6ab05d92..8775f44c 100644 --- a/justfile +++ b/justfile @@ -29,15 +29,15 @@ test-wasm-browser: test-wasm-node: ./gradlew wasmNodeTest -native-desktop-task := ( +native-host-test-task := ( if os() == "macos" { "macosArm64Test" } else if os() == "linux" { "linuxX64Test" } else if os() == "windows" { "mingwX64Test" } else { error("Unrecognized OS: " + os()) } ) -test-native-desktop: - ./gradlew {{ native-desktop-task }} +test-native-host: + ./gradlew {{ native-host-test-task }} test-native-ios: ./gradlew iosSimulatorArm64Test diff --git a/settings.gradle.kts b/settings.gradle.kts index 2febc09a..ce24603e 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -31,6 +31,6 @@ dependencyResolutionManagement { } } -plugins { id("org.gradle.toolchains.foojay-resolver-convention") version ("0.10.0") } +plugins { id("org.gradle.toolchains.foojay-resolver-convention") version ("1.0.0") } include(":", ":demo-app")