From 38063d5cd99dab16173802ae0ee4c60def36ed1c Mon Sep 17 00:00:00 2001 From: Kris Healy Date: Tue, 21 Apr 2015 09:40:14 -0700 Subject: [PATCH 1/3] Adds javadoc building to gradle script. Cleans up some javadocs --- build.gradle | 19 ++++++++++ .../com/kissmetrics/sdk/ArchiverImpl.java | 16 ++++---- .../java/com/kissmetrics/sdk/Connection.java | 2 +- .../com/kissmetrics/sdk/ConnectionImpl.java | 4 +- .../com/kissmetrics/sdk/KISSmetricsAPI.java | 38 +++++++++---------- .../com/kissmetrics/sdk/QueryEncoder.java | 8 ++-- .../kissmetrics/sdk/TrackingRunnables.java | 2 - .../TrackingRunnablesNonTrackingState.java | 2 - .../sdk/TrackingRunnablesTrackingState.java | 2 - .../com/kissmetrics/sdk/package-info.java | 4 ++ 10 files changed, 52 insertions(+), 45 deletions(-) create mode 100644 src/main/java/com/kissmetrics/sdk/package-info.java diff --git a/build.gradle b/build.gradle index 78a2a8d..6064895 100644 --- a/build.gradle +++ b/build.gradle @@ -67,4 +67,23 @@ android.libraryVariants.all { variant -> task.dependsOn variant.javaCompile task.from variant.javaCompile.destinationDir artifacts.add('archives', task); +} + +// This magic came from: +// http://stackoverflow.com/questions/23297562/gradle-javadoc-and-android-documentation +android.libraryVariants.all { variant -> + task("generate${variant.name.capitalize()}Javadoc", type: Javadoc) { + title = "KISSmetrics Android API ${android.defaultConfig.versionName}" + description = 'Documentation for the KISSmetrics Android API' + + source = variant.javaCompile.source + classpath = files(variant.javaCompile.classpath.files, project.android.getBootClasspath()) + options { + links "http://docs.oracle.com/javase/7/docs/api/" + linksOffline "http://d.android.com/reference","${android.sdkDirectory}/docs/reference" + } + exclude '**/BuildConfig.java' + exclude '**/R.java' + exclude '**/doc-files/*' + } } \ No newline at end of file diff --git a/src/main/java/com/kissmetrics/sdk/ArchiverImpl.java b/src/main/java/com/kissmetrics/sdk/ArchiverImpl.java index 286c659..a6d909a 100644 --- a/src/main/java/com/kissmetrics/sdk/ArchiverImpl.java +++ b/src/main/java/com/kissmetrics/sdk/ArchiverImpl.java @@ -33,8 +33,6 @@ import android.util.Log; /** - * ArchiverImpl - *

* Handles read/write of settings, identity, recorded events and properties. * Recorded events and properties are URL encoded before being saved to a send queue. */ @@ -408,7 +406,7 @@ private long currentTimeSeconds() { ************************************************/ /** - * Archives install UUID to Settings > Internal Storage. + * Archives install UUID to Settings < Internal Storage. * * @param installUuid Unique identifier of the application install which may only be * archived once. @@ -430,7 +428,7 @@ public void archiveInstallUuid(final String installUuid) { } /** - * Archives doTrack boolean to Settings > Internal Storage. + * Archives doTrack boolean to Settings < Internal Storage. * * @param doTrack Setting to control recording of aliases, events and properties. */ @@ -442,7 +440,7 @@ public void archiveDoTrack(boolean doTrack) { } /** - * Archives doSend boolean to Settings > Internal Storage. + * Archives doSend boolean to Settings < Internal Storage. * * @param doSend Setting to control the uploading of aliases, events and properties. */ @@ -454,7 +452,7 @@ public void archiveDoSend(boolean doSend) { } /** - * Archives baseUrl String to Settings > Internal Storage. + * Archives baseUrl String to Settings < Internal Storage. * * @param baseUrl Setting for API base URL path */ @@ -472,7 +470,7 @@ public void archiveBaseUrl(String baseUrl) { } /** - * Archives doTrack verification expiration date to Settings > Internal Storage. + * Archives doTrack verification expiration date to Settings < Internal Storage. * * @param expDate Milliseconds from unix epoch when verification expires. */ @@ -484,7 +482,7 @@ public void archiveVerificationExpDate(long expDate) { } /** - * Archives hasGenericIdentity boolean to Settings > Internal Storage. + * Archives hasGenericIdentity boolean to Settings < Internal Storage. * * @param hasGenericIdentity setting to indicate that a proper identity has been given. */ @@ -495,7 +493,7 @@ public void archiveHasGenericIdentity(final boolean hasGenericIdentity) { } /** - * Archives appVersion to Settings > Internal Storage. + * Archives appVersion to Settings < Internal Storage. * * @param appVersion String app version name. */ diff --git a/src/main/java/com/kissmetrics/sdk/Connection.java b/src/main/java/com/kissmetrics/sdk/Connection.java index a296294..fa5876e 100644 --- a/src/main/java/com/kissmetrics/sdk/Connection.java +++ b/src/main/java/com/kissmetrics/sdk/Connection.java @@ -28,7 +28,7 @@ interface Connection { * Handles the response and notifies the provided ConnectionDelgate on completion. * * @param urlString URL encoded API query string - * @delegate delegate Object implementing the ConnectionDelegate interface + * @param delegate Object implementing the ConnectionDelegate interface */ void sendRecord(String urlString, ConnectionDelegate delegate); } diff --git a/src/main/java/com/kissmetrics/sdk/ConnectionImpl.java b/src/main/java/com/kissmetrics/sdk/ConnectionImpl.java index 1c6c789..2c149ce 100644 --- a/src/main/java/com/kissmetrics/sdk/ConnectionImpl.java +++ b/src/main/java/com/kissmetrics/sdk/ConnectionImpl.java @@ -26,8 +26,6 @@ import android.util.Log; /** - * ConnectionImpl - *

* Handles HttpURLConnections for KISSmetrics API queries. */ public class ConnectionImpl implements Connection { @@ -52,7 +50,7 @@ protected HttpURLConnection createHttpURLConnection(URL url) throws IOException * Handles the response and notifies the provided ConnectionDelgate on completion. * * @param urlString URL encoded API query string - * @delegate delegate Object implementing the ConnectionDelegate interface + * @param delegate Object implementing the ConnectionDelegate interface */ public void sendRecord(String urlString, ConnectionDelegate delegate) { URL url = null; diff --git a/src/main/java/com/kissmetrics/sdk/KISSmetricsAPI.java b/src/main/java/com/kissmetrics/sdk/KISSmetricsAPI.java index 10c6525..59621c1 100644 --- a/src/main/java/com/kissmetrics/sdk/KISSmetricsAPI.java +++ b/src/main/java/com/kissmetrics/sdk/KISSmetricsAPI.java @@ -27,8 +27,6 @@ import android.util.Log; /** - * KISSmetricsAPI - *

* Public API for sending identities, events and properties to KISSmetrics from * Android applications. Compatible with Android 2.2+ */ @@ -66,7 +64,7 @@ protected static void setVerificationImpl(VerificationImpl verImpl) { /** * Initializes the default Connection if not set. Allows for injection of * mock HttpURLConnection within VerificationImpl. - *

+ * * Returns the injected verificationImpl if it exists. * * @return Connection @@ -405,7 +403,7 @@ public void autoSetAppProperties() { } } - /** + /* * ********************************************* * VerificationDelegateInterface methods * ********************************************** @@ -457,15 +455,16 @@ public void verificationComplete(boolean success, ************************************************/ /** + * Initializes and/or returns the KISSmetricsAPI singleton + * instance. + * * @param apiKey KISSmetrics product key * @param context Android application context * @param secure !Ignored! * @return singleton instance of the KISSmeticsAPI - * @deprecated use {@link sharedAPI(String apiKey)} instead. All requests + * + * @deprecated use {@link #sharedAPI(String, android.content.Context)} instead. All requests * are now made over https. secure(boolean) is ignored. - *

- * Initializes and/or returns the KISSmetricsAPI singleton - * instance. */ @Deprecated public static synchronized KISSmetricsAPI sharedAPI(String apiKey, @@ -478,13 +477,12 @@ public static synchronized KISSmetricsAPI sharedAPI(String apiKey, } /** + * Records an event with optional properties. + * * @param name Event name * @param properties Event properties or null - * @deprecated use {@link record(String name, Map - * properties)} instead. 'recordEvent' method name has been - * changed to 'record' for consistency across our various APIs. - *

- * Records an event with optional properties. + * @deprecated use {@link #record(String, java.util.Map)} instead. 'recordEvent' method name + * has been changed to 'record' for consistency across our various APIs. */ @Deprecated public void recordEvent(String name, Map properties) { @@ -493,11 +491,10 @@ public void recordEvent(String name, Map properties) { /** * @param name Event name - * @deprecated use {@link record(String name, Map - * properties), RecordCondition condition} instead. 'recordOnce' - * would only restrict the recording of events per identity. A - * more flexible solution was needed to allow recording of - * events once per installation or identity. + * @deprecated use {@link #record(String, java.util.Map, com.kissmetrics.sdk.KISSmetricsAPI.RecordCondition)} + * instead. 'recordOnce' would only restrict the recording of events per identity. A + * more flexible solution was needed to allow recording of events once per installation or + * identity. */ @Deprecated public void recordOnce(String name) { @@ -507,9 +504,8 @@ public void recordOnce(String name) { /** * @param properties User properties - * @deprecated use {@link set(Map properties)} instead. - * 'setProperties' method name has been changed to 'set' for - * consistency across our various APIs. + * @deprecated use {@link #set(java.util.Map)} instead. setProperties method name + * has been changed to 'set' for consistency across our various APIs. */ @Deprecated public void setProperties(Map properties) { diff --git a/src/main/java/com/kissmetrics/sdk/QueryEncoder.java b/src/main/java/com/kissmetrics/sdk/QueryEncoder.java index d3e821d..c01a1ea 100644 --- a/src/main/java/com/kissmetrics/sdk/QueryEncoder.java +++ b/src/main/java/com/kissmetrics/sdk/QueryEncoder.java @@ -25,8 +25,6 @@ import android.util.Log; /** - * QueryEncoder - *

* URL encoder for KISSmetricsAPI queries. */ public class QueryEncoder { @@ -51,7 +49,7 @@ public QueryEncoder(String key, String clientType, String userAgent) { } /** - * Checks provided properties HashMap for _d & _t timestamp keys. + * Checks provided properties HashMap for _d & _t timestamp keys. * * @param properties HashMap of user or event properties * @return boolean true if timestamp has been set in these properties @@ -172,7 +170,7 @@ public String encodeProperties(Map properties) { * @param name Event name * @param properties Event properties * @param identity User identity - * @param timestamp A unix epoch timestamp to apply if _t & _d have not been set in properties + * @param timestamp A unix epoch timestamp to apply if _t & _d have not been set in properties * @return the URL encoded query string */ public String createEventQuery(String name, @@ -198,7 +196,7 @@ clientType, userAgent, encodeIdentity(identity), * * @param properties User properties * @param identity User identity - * @param timestamp A unix epoch timestamp to apply if _t & _d have not been set in properties + * @param timestamp A unix epoch timestamp to apply if _t & _d have not been set in properties * @return the URL encoded query string */ public String createPropertiesQuery(Map properties, diff --git a/src/main/java/com/kissmetrics/sdk/TrackingRunnables.java b/src/main/java/com/kissmetrics/sdk/TrackingRunnables.java index 3493af9..544bbda 100644 --- a/src/main/java/com/kissmetrics/sdk/TrackingRunnables.java +++ b/src/main/java/com/kissmetrics/sdk/TrackingRunnables.java @@ -22,8 +22,6 @@ import java.util.Map; /** - * TrackingRunnables interface - *

* Classes implementing this interface provide Runnable objects to * handle tracking for specific tracking states. */ diff --git a/src/main/java/com/kissmetrics/sdk/TrackingRunnablesNonTrackingState.java b/src/main/java/com/kissmetrics/sdk/TrackingRunnablesNonTrackingState.java index a754d11..424e79f 100644 --- a/src/main/java/com/kissmetrics/sdk/TrackingRunnablesNonTrackingState.java +++ b/src/main/java/com/kissmetrics/sdk/TrackingRunnablesNonTrackingState.java @@ -22,8 +22,6 @@ import com.kissmetrics.sdk.KISSmetricsAPI.RecordCondition; /** - * TrackingRunnables non-tracking state - *

* Provides Runnable objects for non-tracking state. */ public class TrackingRunnablesNonTrackingState implements TrackingRunnables { diff --git a/src/main/java/com/kissmetrics/sdk/TrackingRunnablesTrackingState.java b/src/main/java/com/kissmetrics/sdk/TrackingRunnablesTrackingState.java index 1d8de50..e272bf1 100644 --- a/src/main/java/com/kissmetrics/sdk/TrackingRunnablesTrackingState.java +++ b/src/main/java/com/kissmetrics/sdk/TrackingRunnablesTrackingState.java @@ -22,8 +22,6 @@ import com.kissmetrics.sdk.KISSmetricsAPI.RecordCondition; /** - * TrackingRunnables tracking state - *

* Provides Runnable objects for tracking state. */ public class TrackingRunnablesTrackingState implements TrackingRunnables { diff --git a/src/main/java/com/kissmetrics/sdk/package-info.java b/src/main/java/com/kissmetrics/sdk/package-info.java new file mode 100644 index 0000000..f45274d --- /dev/null +++ b/src/main/java/com/kissmetrics/sdk/package-info.java @@ -0,0 +1,4 @@ +/** + * + */ +package com.kissmetrics.sdk; \ No newline at end of file From 9f0dd416c5b520290547bff847c6b16890d84cde Mon Sep 17 00:00:00 2001 From: Kris Healy Date: Thu, 23 Apr 2015 09:20:01 -0700 Subject: [PATCH 2/3] Tweaks build file some more for javadocs/jar'ing. Bumps version number --- build.gradle | 48 ++++++++++++++++++++++-------------- src/main/AndroidManifest.xml | 4 +-- 2 files changed, 30 insertions(+), 22 deletions(-) diff --git a/build.gradle b/build.gradle index 6064895..55e06ec 100644 --- a/build.gradle +++ b/build.gradle @@ -4,7 +4,7 @@ buildscript { } dependencies { - classpath 'com.android.tools.build:gradle:1.1.0' + classpath 'com.android.tools.build:gradle:1.1.+' } } @@ -17,8 +17,8 @@ android { defaultConfig { minSdkVersion 8 targetSdkVersion 22 - versionCode 2 - versionName "2.2.1" + versionCode 3 + versionName "2.2.2" } buildTypes { @@ -55,7 +55,8 @@ task wrapper(type: org.gradle.api.tasks.wrapper.Wrapper) { gradleVersion = '2.3' } -// Take from http://stackoverflow.com/questions/19307341/android-library-gradle-release-jar/19484146#19484146 +// Take from +// http://stackoverflow.com/questions/19307341/android-library-gradle-release-jar/19484146#19484146 android.libraryVariants.all { variant -> def name = variant.buildType.name @@ -66,24 +67,33 @@ android.libraryVariants.all { variant -> def task = project.tasks.create "jar${name.capitalize()}", Jar task.dependsOn variant.javaCompile task.from variant.javaCompile.destinationDir - artifacts.add('archives', task); + artifacts.add('archives', task) } // This magic came from: // http://stackoverflow.com/questions/23297562/gradle-javadoc-and-android-documentation -android.libraryVariants.all { variant -> - task("generate${variant.name.capitalize()}Javadoc", type: Javadoc) { - title = "KISSmetrics Android API ${android.defaultConfig.versionName}" - description = 'Documentation for the KISSmetrics Android API' - - source = variant.javaCompile.source - classpath = files(variant.javaCompile.classpath.files, project.android.getBootClasspath()) - options { - links "http://docs.oracle.com/javase/7/docs/api/" - linksOffline "http://d.android.com/reference","${android.sdkDirectory}/docs/reference" - } - exclude '**/BuildConfig.java' - exclude '**/R.java' - exclude '**/doc-files/*' +task javadocs(type: Javadoc) { + title = "KISSmetrics Android API ${android.defaultConfig.versionName}" + description = 'Documentation for the KISSmetrics Android API' + + def variant = android.libraryVariants.release + source = android.sourceSets.main.java.srcDirs + classpath = files(variant.javaCompile.classpath.files, project.android.getBootClasspath()) + options { + links "http://docs.oracle.com/javase/7/docs/api/" + linksOffline "http://d.android.com/reference","${android.sdkDirectory}/docs/reference" } + + exclude '**/BuildConfig.java' + exclude '**/R.java' +} + +task sourcesJar(type: Jar) { + classifier 'sources' + from android.sourceSets.main.java.srcDirs +} + +task javadocsJar(type: Jar, dependsOn: javadocs) { + classifier 'javadoc' + from "${project.buildDir}/docs/javadoc" } \ No newline at end of file diff --git a/src/main/AndroidManifest.xml b/src/main/AndroidManifest.xml index 8d296ea..f108cca 100644 --- a/src/main/AndroidManifest.xml +++ b/src/main/AndroidManifest.xml @@ -1,8 +1,6 @@ + package="com.kissmetrics.sdk"> From 11131d21d178d305cc7c575da5b45e3a90753eea Mon Sep 17 00:00:00 2001 From: Kris Healy Date: Thu, 23 Apr 2015 09:33:42 -0700 Subject: [PATCH 3/3] Release documentation --- releasing.md | 51 +++++++++++++++++++ .../java/com/kissmetrics/sdk/Connection.java | 2 +- 2 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 releasing.md diff --git a/releasing.md b/releasing.md new file mode 100644 index 0000000..90c5ce1 --- /dev/null +++ b/releasing.md @@ -0,0 +1,51 @@ +# Releasing + +### 1. Make sure the tests run + +An important step many may forget: + +```sh +gradle connectedAndroidTest +``` + +You will need an Android emulator running to run the tests. + +### 2. Bump Version Number + +The version number needs to be increased. If it is a feature addition/change +bump the second number (i.e. 2.X.0). If it is a patch/bug fix bump the last +number (i.e. 2.0.X). + +In the `build.gradle` file also bump the `versionCode` number by 1. This is an +Android thing. + +The version number lives in: + + 1. `Connection.java` under `com.kissmetrics.sdk`. It's in the constant `USER_AGENT` + 2. `build.gradle` file at the root. + +### 3. Merge and Tag + +Get your changes into the `master` branch. Then create a tag with the version: + +### 4. Build Artifacts + +You can build everything you need with this command line and Gradle 2.3+: + +```sh +gradle clean build compileReleaseSources javadocs javadocsJar sourcesJar +``` + +It will create the following files: + +``` +build/libs/KISSmetricsSDK-javadoc.jar +build/libs/KISSmetricsSDK-sources.jar +build/libs/KISSmetricsSDK.jar +build/outputs/aar/KISSmetricsSDK-debug.aar +build/outputs/aar/KISSmetricsSDK-release.aar +``` + +### 5. Release + +Create the Release on GitHub. diff --git a/src/main/java/com/kissmetrics/sdk/Connection.java b/src/main/java/com/kissmetrics/sdk/Connection.java index fa5876e..46a2588 100644 --- a/src/main/java/com/kissmetrics/sdk/Connection.java +++ b/src/main/java/com/kissmetrics/sdk/Connection.java @@ -21,7 +21,7 @@ * Connection interface */ interface Connection { - public static final String USER_AGENT = "KISSmetrics-Android/2.2.1"; + public static final String USER_AGENT = "KISSmetrics-Android/2.2.2"; /** * Makes a request to the provided API query urlString.