Merge pull request #3 from d4l-data4life/feature/add-changelog

Add changelog, contributing guide and developing guide

CHANGELOG.adoc

@@ -1,5 +1,6 @@
 = Changelog
 :toc: macro
+:link-repository: https://github.com/d4l-data4life/hc-result-sdk-kmp
 :toclevels: 1
 :toc-title:
 
@@ -12,20 +13,43 @@ and this project adheres to http://semver.org/spec/v2.0.0.html[Semantic Versioni
 ==== Versions
 toc::[]
 
-== https://github.com/d4l-data4life/hc-result-sdk-kmp/compare/0.1.0...main[Unreleased]
+
+== link:{link-repository}/releases/latest[Unreleased]
+See link:{link-repository}/compare/v0.1.0...main[changeset]
 
 === Added
 
 === Changed
 
+=== Deprecated
+
 === Removed
 
 === Fixed
 
+=== Security
+
 === Bumped
 
 === Migration
 
-== https://github.com/d4l-data4life/hc-result-sdk-kmp/compare/v0.1.0[0.1.0]
 
-Initial release taken to be open sourced.
+== link:{link-repository}/releases/tag/v0.1.0[0.1.0]
+
+=== Added
+
+Initial release.
+
+* `D4LSDKFlow` wrapper for all platforms
+* `D4LRuntimeException` as base runtime error for kmp sdks
+* `D4LException` as base error for kmp sdks
+
+=== Changed
+
+=== Removed
+
+=== Fixed
+
+=== Bumped
+
+=== Migration

CONTRIBUTING.adoc

@@ -0,0 +1,106 @@
+= Contributing
+:link-repository: https://github.com/d4l-data4life/hc-result-sdk-kmp
+:doctype: article
+:toc: macro
+:toclevels: 2
+:toc-title:
+:icons: font
+:imagesdir: assets/images
+ifdef::env-github[]
+:warning-caption: :warning:
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+endif::[]
+
+When contributing to this project, this document should help you get started.
+
+[discrete]
+==== Table Of Contents
+
+toc::[]
+
+== Code Of Conduct
+
+This project adheres to the Contributor Covenant link:CODE-OF-CONDUCT.adoc[Code Of Conduct]. By participating, you are expected to uphold this code.
+
+== Issues
+
+We use GitHub issues to track bugs and enhancements.
+
+Issues are very valuable to this project, please feel free to open link:{link-repository}/issues[issues] for:
+
+* _**Questions**_ help us to improve the user experience
+* _**Ideas**_ are a great source for contributions
+* _**Problems**_ show where this project is lacking
+
+If you are reporting a problem, please help to us by providing as much information as possible. Ideally, that includes a description or small sample project how to reproduce the problem.
+
+It’s also a good practice to search for existing or related issues before submitting your own. Thank you!
+
+== Contribute Code
+
+=== Pull Requests
+
+link:{link-repository}/pulls[Pull requests] are a great way to improve the project. But please, discuss your contribution with us before making changes.
+
+If you contribute, you have:
+
+* signed Contributor License Agreement, see <<_licensing>>
+* made clear which problem you're trying to solve
+* followed our link:CODE-OF-CONDUCT.adoc[Code of conduct]
+* followed our link:DEVELOPING.adoc[Development process]
+
+==== Create Pull Request
+
+Please use our title pattern: `[{ticket id}] {type of change} {short description}`:
+
+* Optional: Add `ticket id` in brackets if you have any, otherwise leave it out.
+* `type of change`:
+- *Add* for new features or functionality
+- *Change* for changes in existing features or functionality
+- *Remove* | for removed features or functionality
+- *Fix* for any bug fixes
+- *Security* in case of vulnerabilities
+- *Bump* for dependency updates
+* `short description` of your change
+
+Example:
+
+* Add awesome hashing algorithm
+* [SDK-156] Change thumbnail generation
+
+Pull requests must fill the provided template. Put N/A when a paragraph cannot be filled.
+
+*Labels* should be used (enhancement,bugfix, help wanted etc...) to categorise your contribution.
+
+Important:: Work in progress pull-requests should be created as a draft.
+
+==== Code Review
+
+At least 1 member of the link:https://github.com/orgs/d4l-data4life/teams/phdc-core[PHDC Core Team] will review
+your contribution and validate if these criteria are met:
+
+* [ ] Functional and fitting in the project
+* [ ] Code style and naming conventions followed
+* [ ] Test written and passing
+* [ ] Continuous Integration build passing
+* [ ] Cross platform testing done for all supported platforms
+* [ ] Documentation updated
+* [ ] Changelog updated
+
+[#_licensing]
+== Licensing
+
+Due to the private link:LICENSE[License] this repository is published under, external contributors need to sign a
+Contributor License Agreement. Please get in contact with mailto:&#109;o&#98;&#x69;&#x6c;&#x65;&#x40;&#100;&#x61;&#x74;a&#52;&#x6c;&#105;f&#101;&#46;&#99;a&#114;e[&#109;o&#98;&#x69;&#x6c;&#x65;&#x40;&#100;&#x61;&#x74;a&#52;&#x6c;&#105;f&#101;&#46;&#99;a&#114;e] before contributing to the project.
+
+== Components Using Other Licenses
+
+Contributing code and introducing dependencies into the repository from other projects that use one of the following licenses is allowed.
+
+* link:https://opensource.org/licenses/MIT[MIT]
+* link:https://opensource.org/licenses/Apache-2.0[Apache 2.0]
+
+Any other contribution needs to be signed off by the project owners.

DEVELOPING.adoc

@@ -0,0 +1,124 @@
+= Developing
+:link-repository: https://github.com/d4l-data4life/hc-result-sdk-kmp
+:doctype: article
+:toc: macro
+:toclevels: 2
+:toc-title:
+:icons: font
+:imagesdir: assets/images
+ifdef::env-github[]
+:warning-caption: :warning:
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+endif::[]
+
+Guide for our development process, project setup and how to write code.
+
+[discrete]
+==== Table Of Contents
+
+toc::[]
+
+== Prerequisites
+
+* link:https://developer.android.com/studio#downloads[Android Studio 4.2.2]
+* link:https://adoptopenjdk.net/?variant=openjdk8&jvmVariant=hotspot[Java 8] | link:https://developer.android.com/studio/write/java8-support[Limitations of Java language features and APIs] | https://jakewharton.com/d8-library-desugaring/[Desugaring]
+* link:https://kotlinlang.org/[Kotlin 1.4.32]
+
+== Installation
+
+=== Install Java & Kotlin
+
+You could use link:https://brew.sh/[Homebrew] to install on mac
+
+[source,bash]
+----
+brew tap adoptopenjdk/openjdk
+brew install adoptopenjdk8
+brew install kotlin
+----
+
+OR The easiest way to install Java and Kotlin is to use link:https://sdkman.io/[SDK MAN]
+
+Just open your terminal and enter:
+
+[source,bash]
+----
+curl -s "https://get.sdkman.io" | bash
+----
+
+Follow the setup instructions and verify that your installation works:
+
+[source,bash]
+----
+sdk version
+----
+
+If it shows you something like `5.11.5+713` then your good to continue.
+
+Just install the mentioned dependencies:
+
+[source,bash]
+----
+sdk install java 8.0.292.hs-adpt
+sdk install kotlin 1.4.32
+----
+
+Check your installation by:
+
+[source,bash]
+----
+java -version
+kotlin -version
+----
+
+=== Android Studio
+
+For better interop with iOS you may install the link:https://plugins.jetbrains.com/plugin/14936-kotlin-multiplatform-mobile[KMM plugin for Android Studio]. It let's you run, test and debug shared code on Android and iOS without switching the IDEs.
+
+== Development Process
+
+=== Features
+
+Every change has to branch of from `main` and use this branch naming convention:
+
+* `feature/{type_of_change}-{short_description}` or with ticket id `feature/{ticket_id}/{type_of_change}-{short_description}`
+
+`main` must be always in releasable state.
+
+==== Type Of Change
+
+- *add* for new features or functionality
+- *change* for changes in existing features or functionality
+- *remove* | for removed features or functionality
+- *fix* for any bug fixes
+- *bump* for dependency updates
+- *security* in case of vulnerabilities
+
+Examples:
+
+- `feature/SDK-456/add-awesome-hashing-algorithm`
+- `feature/add-awesome-hashing-algorithm`
+- `feature/remove-not-so-awesome-algorithm`
+- `feature/fix-algorithm-corner-case`
+- `feature/bump-lib-to-1.3.0`
+
+== Release
+
+A release branches of from `main` branch with following pattern:
+
+* `release/{major}.{minor}(.{patch})/prepare-{major}.{minor}.{patch}` while patch is optional
+
+Add following changes:
+
+* Update CHANGELOG.adoc by creating a new Unreleased section and change current unreleased to release version
+* Update README.adoc to release version
+* Update the latest release badge link:assets/images/badges.adoc[HowTo]
+
+Releases are automatically created when a tag in the form of `v{major}.{minor}.{patch}` is added.
+
+== Develop
+
+TODO

README.adoc

@@ -134,17 +134,27 @@ dependencies {
 
 This project is work in progress. We are working on adding more functionality, guidelines, documentation and other improvements.
 
-== Contributing
+== Changelog
+
+See link:CHANGELOG.adoc[changelog]
+
+== Versioning
 
-You want to help or share a proposal? You have a specific problem? Then open an issue.
+We use http://semver.org/[Semantic Versioning] as a guideline for our versioning.
 
-=== Contribution Guide
+Releases use this format: `{major}.{minor}.{patch}`
 
-Will be added soon.
+* Breaking changes bump `{major}` and reset `{minor}` & `{patch}`
+* Backward compatible changes bump `{minor}` and reset `{patch}`
+* Bug fixes bump `{patch}`
+
+== Contributing
 
-=== Development Guide
+You want to help or share a proposal? You have a specific problem? Read the following:
 
-More content will be added soon.
+* link:CODE-OF-CONDUCT.adoc[Code of conduct] for details on our code of conduct.
+* link:CONTRIBUTING.adoc[Contributing] for details about how to report bugs and propose features.
+* link:DEVELOPING.adoc[Developing] for details about our development process and how to build and test the project.
 
 == Copyright and License