[HEAP-40116][HEAP-41239] Add project documents and bump version to 0.…

…1.0 (#56)

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Manual capture SDK.
+- Support methods and classes for runtime bridges.
+- Support methods and classes for autocapture sources.
+- Support for manual capture within WKWebView.
+- Support for platforms targeting Swift: macOS, watchOS, iOS, iPadOS, tvOS.
+
+[0.1.0]: https://github.com/heap/heap-swift-core-sdk/releases/tag/0.1.0

DevTools/LibraryVersions.py

@@ -92,6 +92,17 @@ def UpdateFiles(version_string):
                                  version_swift_content)
   open(_VERSION_SWIFT_PATH, 'w').write(version_swift_content)
 
+def ReadVersion():
+  version_swift_content = open(_VERSION_SWIFT_PATH).read()
+  major = re.search(r'static let major = (\d+)\n', version_swift_content).group(1)
+  minor = re.search(r'static let minor = (\d+)\n', version_swift_content).group(1)
+  revision = re.search(r'static let revision = (\d+)\n', version_swift_content).group(1)
+  prerelease = re.search(r'static let prerelease: String\? = "([^"]+)"\n', version_swift_content)
+
+  if prerelease:
+    return '%s.%s.%s-%s' % ( major, minor, revision, prerelease.group(1) )
+  else:
+    return '%s.%s.%s' % ( major, minor, revision )
 
 def main(args):
   usage = '%prog [OPTIONS] [VERSION]'
@@ -102,20 +113,35 @@ def main(args):
   parser.add_option('--validate',
                     default=False, action='store_true',
                     help='Check if the versions in all the files match.')
+  parser.add_option('--print',
+                    default=False, action='store_true',
+                    help='Prints the version string.')
   opts, extra_args = parser.parse_args(args)
 
+  if opts.validate and opts.print:
+    parser.error('--print and --validate are mutually exclusive.')
+
+  if opts.print:
+    if extra_args:
+      parser.error('No version can be given when using --validate.')
+
+    print(ReadVersion())
+    return 0
+
   if opts.validate:
     if extra_args:
       parser.error('No version can be given when using --validate.')
-  else:
-    if len(extra_args) != 1:
-      parser.error('Expected one argument, the version number to ensure is in the sources.')
-    if not _VERSION_RE.match(extra_args[0]):
-      parser.error('Version does not appear to be in the form of x.y.z.')
-
-  # Always validate, just use the flag to tell if we're expected to also have set something.
-  if not opts.validate:
-    UpdateFiles(extra_args[0])
+
+    ValidateFiles()
+    return 0
+
+  if len(extra_args) != 1:
+    parser.error('Expected one argument, the version number to ensure is in the sources.')
+
+  if not _VERSION_RE.match(extra_args[0]):
+    parser.error('Version does not appear to be in the form of x.y.z.')
+
+  UpdateFiles(extra_args[0])
   ValidateFiles()
   return 0
 

DevTools/ReleaseFromRemoteBranch.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# DevTools/ReleaseFromRemoteBranch.sh - Helper for tagging the remote head of the repo
+#
+# Copyright (c) 2022 Heap Inc.
+#
+# Usage:
+# ./DevTools/ReleaseFromRemoteBranch.sh [BRANCH]
+# 
+# make release_from_origin_main
+#
+# This makes it harder to accidentally tag the wrong commit or use the wrong version.
+
+set -o errexit
+
+BRANCH="${1:-main}"
+
+TMP_DIR=$(mktemp -d -t heap-ios-autocapture)
+REPO_DIR="${TMP_DIR}/heap-ios-autocapture"
+
+REPO='[email protected]:heap/heap-swift-autocapture.git'
+
+echo "--- Cloning branch ${BRANCH} of ${REPO}"
+
+git clone --depth 1 -b "${BRANCH}" "${REPO}" "${REPO_DIR}"
+
+VERSION=$("${REPO_DIR}"/DevTools/LibraryVersions.py --print)
+
+echo "--- Pushing tag ${VERSION} from branch ${BRANCH}"
+cd  "${REPO_DIR}"
+
+git tag "${VERSION}"
+git push origin "${VERSION}"

Development/README.md

@@ -0,0 +1,96 @@
+# HeapSwiftCore Development
+
+This directory is used for development of HeapSwiftCore.
+
+## Project structure
+
+Since Xcode downloads all dependencies specified in `/Package.swift` and a `Package.swift` file cannot reference sources outside it, this
+project uses the following structure:
+
+```
+heap-swift-core
+┗ Package.swift (public)
+┗ Development
+  ┗ Package.swift (development)
+  ┗ Sources
+  ┃ ┗ HeapSwiftCore
+  ┃ ┗ HeapSwiftCoreTestSupport
+  ┃ ┗ Protobufs
+  ┗ Tests
+    ┗ HeapSwiftCoreTests
+    ┗ HeapSwiftCoreTests-AdSupport
+```
+
+This allows development to happen in the `Development` directory without pulling in test dependencies.  In general, the parent package
+and the child should be the same except that the parent only contains the code required in an app.
+
+# Documents
+
+The behavior of this project is defined in the [Capture Core SDKs][specs] documentation folder (Heap internal).
+
+# Installation and Usage
+
+Heap can be installed using the developer instructions at https://developers.heap.io/docs/ios
+
+During development, HeapSwiftCore can be added to an Xcode project or Swift package using `[email protected]:heap/heap-swift-core.git` or the
+mirror at `[email protected]:heap/heap-swift-core-sdk.git`.
+
+Once the repo is made public, users will be able to using `https://github.com/heap/heap-swift-core.git`.
+
+For projects that require Cocoapods, such as the development of React Native and Flutter SDKs, there is a private repo at
+https://github.com/heap/pre-release-cocoapods.  You can add it as a local pod repository using
+`pod repo add pre-release-cocoapods [email protected]:heap/pre-release-cocoapods.git main`.  Once added, you can use it by adding the following
+to the top of your `Podfile`:
+
+```
+source '[email protected]:heap/pre-release-cocoapods.git'
+source 'https://cdn.cocoapods.org/'
+```
+
+Then you can then add it as a dependency in your podspec with `s.dependency 'HeapSwiftCore'`.
+
+Once this repo is made public, you will be able to remove references to `pre-release-cocoapods`.
+
+# Usage
+
+Heap can be initialized using `Heap.shared.startRecording("YOUR_APP_ID")`.  Once initialized, you can track events using
+`Heap.shared.track("event name")` and use other functions covered in the documentation.
+
+If at any point you wish to disable tracking, simply call `Heap.shared.stopRecording()`.
+
+By default, Heap will log messages that will be informative in a production environment.  To enable messages that may be helpful in a
+development environment, use `HeapLogger.shared.logLevel = .debug`.  To enable messages for troubleshooting complex issues, use
+`HeapLogger.shared.loglevel = .trace`.
+
+Log messages will appear in the Xcode log window and, with the exception of trace messages, will also appear in Console.app. You can
+redirect messages to another channel implementing `LogChannel` and setting `HeapLogger.shared.logChannel to an instance of your class.
+
+# Dependencies
+
+- HeapSwiftCore has one runtime dependency, [swift-protobuf v1.x](https://github.com/apple/swift-protobuf), which it uses to build payloads
+  to send to the server.
+- HeapSwiftCore also has two testing dependencies, [Quick](https://github.com/Quick/Quick) and [Nimble](https://github.com/Quick/Nimble),
+  which are used for BDD-style testing.
+
+# Development
+
+HeapSwiftCore is packaged as a Swift Package and can be developed on by opening the folder in either Xcode or Visual Studio Code.  Sources
+exist in [Sources](Sources/) and tests exist in [Tests](Tests/).  There are also example apps in [Examples](Examples/) which can be used for
+manually validating Heap.
+
+# CI Pipeline
+
+Each branch pushed to the server triggers a build in [the repo-heap-swift-core-required BuildKite pipeline][buildkite-req].  This pipeline
+is defined in [../.buildkite/buildkite_required.yml](../.buildkite/buildkite_required.yml), which triggers various targets in
+[../Makefile](../Makefile).  The latest commit must pass this build in order for a PR to be merged.
+
+Steps in the CI pipeline can be executed manually by running the make targets in the root directory.  For example, you can run
+`make iphone_ios12_unit_tests`, which is roughly equivalent of running the tests in Xcode with an iOS 12 simulator.  Tests that run on a
+non-macOS device will create a temporary simulator which is destroyed at the end of testing.
+
+The specifics of the CI system are described in the [iOS CI Infrastructure][ci] document (Heap internal).
+
+
+[specs]: https://heapinc.atlassian.net/wiki/spaces/CAP/pages/2604990512/Capture+Core+SDKs
+[buildkite-req]: https://buildkite.com/heap/repo-heap-swift-core-required
+[ci]: https://heapinc.atlassian.net/wiki/spaces/CAP/pages/1327202313/iOS+CI+Infrastructure

Development/Sources/HeapSwiftCore/Version.swift

@@ -5,10 +5,10 @@ struct Version {
     static let major = 0
 
     /// Minor version.
-    static let minor = 0
+    static let minor = 1
 
     /// Revision number.
-    static let revision = 3
+    static let revision = 0
 
     /// Optional pre-release version
     static let prerelease: String? = nil

HeapSwiftCore.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name = 'HeapSwiftCore'
-  s.version = '0.0.3'
+  s.version = '0.1.0'
   s.license = { :type => 'Commercial', :text => 'See https://heapanalytics.com/terms' }
   s.summary = 'The core Heap library used for apps on Apple platforms.'
   s.homepage = 'https://heap.io'

LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Heap Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -257,3 +257,7 @@ endif
 
 	git fetch origin --tags
 	git push public ${BUILDKITE_TAG}
+
+release_from_origin_main:
+
+	./DevTools/ReleaseFromRemoteBranch.sh

README.md

@@ -1 +1,27 @@
-# Heap-Swift-Core
+# HeapSwiftCore
+
+HeapSwiftCore is an implementation of the Heap SDK for Apple systems that support Swift (iOS, iPadOS, tvOS, macOS, and watchOS). It serves
+several purposes:
+
+- It provides the base SDK for initializing Heap and sending manual events, e.g. `Heap.shared.startRecording("YOUR_APP_ID")` and
+  `Heap.shared.track("applied discount", properties: [ "coupon code": couponCode ])`.
+- It manages the storage and upload of events.
+- It provides functions that allow autocapture frameworks to send events, e.g., `Heap.shared.trackPageview` and
+  `Heap.shared.trackInteraction`.
+- It provides delegate methods that allow autocapture frameworks to respond to system events, i.e. `Heap.shared.addSource`.
+- It provides support tools for bridging to other runtimes and languages, i.e., `HeapBridgeSupport` and `Heap.shared.addBridge`.
+- It provides support for web view event capture using the bridging mechanisms described above.
+
+## Installation and Usage
+
+Heap can be installed using the developer instructions at https://developers.heap.io/docs/ios
+
+## Dependencies
+
+HeapSwiftCore has one dependency, [swift-protobuf v1.x](https://github.com/apple/swift-protobuf), which it uses to build payloads to send
+to the server.
+
+## Development
+
+HeapSwiftCore development happens within the [Development](Development/) directory and more detailed instructions at
+[Development/README.md](Development/README.md).