diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index c0252ae..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: Bug report -about: Create a report to help us improve - ---- - -## :writing_hand: Describe the bug - - -## :bomb: Steps to reproduce - -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error - -## :wrench: Expected behavior - - -## :camera: Screenshots - - -## :iphone: Tech info - - Device: - - OS: - - Sentinel version: - -## :page_facing_up: Additional context - \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..9a776bf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,54 @@ +name: Bug report +description: Create a report to help us improve +labels: bug +body: + - type: textarea + id: description + attributes: + label: 📖 Description + description: A clear and concise description of what the bug is. + validations: + required: true + - type: textarea + id: environment + attributes: + label: ℹī¸ Environment + description: | + An environment information where issue occurred. Try to provide as much information as possible, including: + - device name, model and manufacturer (e.g. Google Pixel 9) + - operating system version (e.g. Android 12) + - software name, version and build number (e.g The Library 4.2.1) + - additional information (e.g. dependencies, IDE, etc.) + value: | + - Device: + - Operating system: + - Software information: + - Additional information: + validations: + required: true + - type: textarea + id: reproduction-steps + attributes: + label: đŸ’Ŗ Steps to reproduce + description: Steps to reproduce the behavior. + value: | + 1. Go to '...' + 2. Click on '....' + 3. Scroll down to '....' + ... + validations: + required: true + - type: textarea + id: expected-behavior + attributes: + label: 🔧 Expected behavior + description: A clear and concise description of what you expected to happen. + validations: + required: true + - type: textarea + id: additional-information + attributes: + label: 📄 Additional information + description: Any additional information that might be helpful in solving the issue. Including screenshots, logs, etc. + validations: + required: false \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index 664dd8d..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project - ---- - -## :warning: Please describe your feature request - - -## :bulb: Describe the solution you'd like - - -## :bar_chart: Describe alternatives you've considered - - -## :page_facing_up: Additional context - - -## :raising_hand: Do you want to develop this feature yourself? - -- [ ] Yes -- [ ] No \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..28c7898 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,25 @@ +name: Feature request +description: Propose a new feature or an idea for this project +labels: enhancement +body: + - type: textarea + id: feature-description + attributes: + label: 💡 Feature description + description: A clear and concise description of the feature request, including what problem it solves. + validations: + required: true + - type: textarea + id: additional-information + attributes: + label: ℹī¸ Additional information + description: An additional information or screenshots about the feature request. + validations: + required: false + - type: textarea + id: alternatives + attributes: + label: 🤔 Describe alternatives you've considered + description: Can you think of alternative approaches to achieve same goal? + validations: + required: false \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE deleted file mode 100644 index 4282bca..0000000 --- a/.github/PULL_REQUEST_TEMPLATE +++ /dev/null @@ -1,20 +0,0 @@ -## :camera: Screenshots - - -## :page_facing_up: Context - - -## :pencil: Changes - - -## :paperclip: Related PR - - -## :no_entry_sign: Breaking - - -## :hammer_and_wrench: How to test - - -## :stopwatch: Next steps - \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..89efece --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,42 @@ +## Summary + + + +## Changes + +### Type + +- [ ] **Feature**: This pull request introduces a new feature. +- [ ] **Bug fix**: This pull request fixes a bug. +- [ ] **Refactor**: This pull request refactors existing code. +- [ ] **Documentation**: This pull request updates documentation. +- [ ] **Other**: This pull request makes other changes. + +#### Additional information + +- [ ] This pull request introduces a **breaking change**. + +### Description + + + +## Checklist + +- [ ] I have performed a self-review of my own code. +- [ ] I have tested my changes, including edge cases. +- [ ] I have added necessary tests for the changes introduced (if applicable). +- [ ] I have updated the documentation to reflect my changes (if applicable). + +## Additional notes + + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 0dfdf5b..c6bb7e1 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,128 +1,74 @@ -# Contributor Covenant Code of Conduct +# Code of conduct -## Our Pledge +## Our pledge -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity -and orientation. +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. +## Our standards -## Our Standards +Examples of behavior that contributes to creating a positive environment +include: -Examples of behavior that contributes to a positive environment for our -community include: +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community +Examples of unacceptable behavior by participants include: -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks * Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission +* Publishing others' private information, such as a physical or electronic + address, without explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting -## Enforcement Responsibilities +## Our responsibilities -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. ## Scope -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -bojan.komljenovic@infinum.com. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. +reported by contacting the project team at opensource@infinum.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct -enforcement ladder](https://github.com/mozilla/diversity). - -[homepage]: https://www.contributor-covenant.org +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 1.4, +available [here](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html). -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. +For answers to common questions about this code of conduct, visit +the [FAQ](https://www.contributor-covenant.org/faq) page. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d31902d..32737ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,43 @@ -Feedback and code contributions are very much welcome. Just make a pull request with a short description of your changes. By making contributions to this project you give permission for your code to be used under the same [license](LICENSE). +# Contributing guidelines -For easier developing a `sample` application with proper implementations is provided. +Welcome to our project! We appreciate your interest in helping us improve it. -Pushing changes directly into master branch is not allowed, please create a separate branch with your changes and then create a pull request. +## How can I contribute? + +There are multiple ways in which you can help us make this project even better. + +- Contributing code improvements or new features +- Writing, updating, or fixing tests +- Improving documentation, including inline comments, user manuals, and developer guides + +## Making changes + +To make changes to the project, please follow these steps: + +1. Fork the project repository. +2. Create a new branch for your changes, based on the project's main branch. +3. Make your changes. Ensure you've followed the coding style and standards. +4. Test your changes thoroughly, ensuring all existing tests pass and new tests cover your changes where appropriate. +5. Commit your changes with a clear and descriptive commit message. +6. Push your changes to your fork. +7. Create a pull request to the project's main branch. + +Once we check everything, we will merge the changes into the main branch and include it in the next release. + +## Guidelines for pull requests + +When submitting a pull request, please ensure that: + +- Your code is properly tested +- Your code adheres to the project's coding standards and style guidelines +- Your commit message is clear and descriptive +- Your pull request includes a description of the changes you have made and why you have made them + +## Code of conduct + +We want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow +our [code of conduct](/CODE_OF_CONDUCT.md). + +## License + +By submitting a pull request you agree to release that code under the project's [license](/LICENSE). diff --git a/README.md b/README.md index b61546e..fb10f5d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Download](https://img.shields.io/maven-central/v/com.infinum.halley/halley-core) ![Validate Gradle Wrapper](https://github.com/infinum/android-halley/workflows/Validate%20Gradle%20Wrapper/badge.svg) +![Download](https://img.shields.io/maven-central/v/com.infinum.halley/halley-core) ![CI](https://github.com/infinum/android-halley/actions/workflows/CI.yml/badge.svg) ### @@ -10,10 +10,23 @@ known just as HAL. Besides manual call sites that core package provides, Retrofit and Ktor integrations are included. _Halley_ is built on top of [KotlinX Serialization](https://github.com/Kotlin/kotlinx.serialization). +## Table of contents + +* [Getting started](#getting-started) +* [Usage](#usage) +* [Models](#models) +* [Comments and limitations](#comments-and-limitations) +* [Deserialization options](#deserialization-options) +* [Requirements](#requirements) +* [Contributing](#contributing) +* [License](#license) +* [Credits](#credits) + ## Getting started There are several ways to include _Halley_ in your project, depending on your use case. -In every case, you should include and apply _Halley_ plugin first. Plugin will include core dependencies and apply KotlinX Serialization in your project. +In every case, you should include and apply _Halley_ plugin first. Plugin will include core dependencies and apply KotlinX Serialization in +your project. You have to add buildscript dependencies in your project level `build.gradle` or `build.gradle.kts`: ### Core - with Halley plugin @@ -41,6 +54,7 @@ buildscript { To include plugin to your project, you have to add buildscript dependencies in your project level `build.gradle` or `build.gradle.kts`: **Groovy** + ```gradle buildscript { repositories { @@ -51,7 +65,9 @@ buildscript { } } ``` + **KotlinDSL** + ```kotlin buildscript { repositories { @@ -66,14 +82,17 @@ buildscript { Then apply the plugin in your app `build.gradle` or `build.gradle.kts` : **Groovy** + ```gradle apply plugin: "com.infinum.halley.plugin" ``` + **KotlinDSL** + ```kotlin plugins { ... - + id("com.infinum.halley.plugin") } ``` @@ -141,7 +160,9 @@ implementation("com.infinum.halley:halley-ktor:0.0.6") ## Usage ### Core + **Serialization** + ```kotlin // create or reuse default Halley instance val halley = Halley() @@ -150,7 +171,9 @@ val result: String = halley.encodeToString( value = ... ) ``` + **Deserialization** + ```kotlin // create or reuse default Halley instance val halley = Halley() @@ -174,8 +197,11 @@ Retrofit.Builder() .baseUrl(baseUrl) .build() ``` + ### Ktor + **Deserialization** + ```kotlin HttpClient(CIO) { defaultRequest { @@ -194,8 +220,11 @@ HttpClient(CIO) { } } ``` + # Models + A typical HAL model class prepared for _Halley_ consists of several parts. + ```kotlin @Serializable data class Model( @@ -214,34 +243,50 @@ data class Model( ) : HalResource ``` + Going from top to bottom, these classes must obey the following list of rules: + * A class must be annotated by KotlinX Serialization `@Serializable`. -* A class must implement an empty `HalResource` interface. -* Classes without `HalResource` interface will be treated like a simple plain JSON. +* A class must implement an empty `HalResource` interface. +* Classes without `HalResource` interface will be treated like a simple plain JSON. * It's recommended to annotate each class property with `@SerialName(value = "...")` to avoid possible ProGuard issues. * HAL _link_ properties must be annotated with `@HalLink` and be `Link` type provided by _Halley_ library. * HAL _embedded_ properties must be annotated with `@HalEmbedded` * Objects under `@HalEmbedded` annotated property must also implement `HalResource` interface. ## Comments and limitations + A few notes about `HalResource` models: -* Kotlin `object` classes are not supported in _Halley_. -* Multiple `Link` classes in one property under one `@HalLink` annotation are supported by using `List`, `Iterable`, `Set`, `Collection` interfaces and `Array` class only. -* Multiple embedded classes in one property under one `@HalEmbedded` annotation are supported by using `List`, `Iterable`, `Set`, `Collection` interfaces and `Array` class only. -* If a model class has `@HalEmbedded` annotated property but server response provides partial or no object in JSON, then _link_ from __links_ part of response JSON will be used to request that resource and populate the parent model before returning the complete parent model. -Please refer to more complex variations of HAL model classes in [sample](https://github.com/infinum/android-halley/tree/main/sample/src/main/kotlin/com/infinum/halley/sample/data/models) module or [test source set in core](https://github.com/infinum/android-halley/tree/main/halley-core/src/test/kotlin/com/infinum/halley/core/shared/models) module of this repository. +* Kotlin `object` classes are not supported in _Halley_. +* Multiple `Link` classes in one property under one `@HalLink` annotation are supported by using `List`, `Iterable`, `Set`, `Collection` + interfaces and `Array` class only. +* Multiple embedded classes in one property under one `@HalEmbedded` annotation are supported by using `List`, `Iterable`, `Set`, + `Collection` interfaces and `Array` class only. +* If a model class has `@HalEmbedded` annotated property but server response provides partial or no object in JSON, then _link_ from _ + _links_ part of response JSON will be used to request that resource and populate the parent model before returning the complete parent + model. + +Please refer to more complex variations of HAL model classes +in [sample](https://github.com/infinum/android-halley/tree/main/sample/src/main/kotlin/com/infinum/halley/sample/data/models) module +or [test source set in core](https://github.com/infinum/android-halley/tree/main/halley-core/src/test/kotlin/com/infinum/halley/core/shared/models) +module of this repository. ## Deserialization options + _Halley_ has 2 ways of providing 3 different option arguments. -Developers can use _imperative_ and _annotated_ way, or both at the same time, to define option arguments depending on integration use case. +Developers can use _imperative_ and _annotated_ way, or both at the same time, to define option arguments depending on integration use +case. If both ways are used, imperative way will override any existing and same keys in the annotations. Option arguments are defined as _common_, _query_ and _template_. + * common - will be appended as HTTP query parameters on **every** link executed by _Halley_ * query - will be appended as HTTP query parameters on **every link with the matching key** executed by _Halley_ -* template - will be replaced on **every link with the matching key** executed by _Halley_ according to [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570) standard +* template - will be replaced on **every link with the matching key** executed by _Halley_ according + to [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570) standard ### Core + ```kotlin // create or reuse default Halley instance val halley = Halley() @@ -264,10 +309,14 @@ val actual: HalModel = halley.decodeFromString( ) ) ``` + ### Retrofit -When using _Halley_ with Retrofit, it is important to ensure that each Retrofit service interface method is annotated with `@HalTag`. + +When using _Halley_ with Retrofit, it is important to ensure that each Retrofit service interface method is annotated with `@HalTag`. The value (any `String` you've chosen) set for the tag will later be used to match the method with the corresponding option arguments. + #### Annotated option arguments in Retrofit service interface + ```kotlin @GET("/Profile/self") @HalCommonArguments( @@ -298,8 +347,12 @@ The value (any `String` you've chosen) set for the tag will later be used to mat @HalTag("profileWithAnnotatedOptions") fun profileWithAnnotatedOptions(): Call ``` + #### Imperative option arguments before Retrofit method call -When setting options imperatively, it is important to ensure that you have used the same **tag** value as the one set in the Retrofit service interface method you intend to use the options for. + +When setting options imperatively, it is important to ensure that you have used the same **tag** value as the one set in the Retrofit +service interface method you intend to use the options for. + ```kotlin private fun fetchProfile() { // Halley for Retrofit provides convenience halleyQueryOptions functions @@ -326,9 +379,14 @@ private fun fetchProfile() { }) } ``` -_Halley_ Retrofit converter factory works as a standalone factory or together with Kotlin Coroutines, RxJava1, RxJava2 and RxJava3 factories. -Various use cases can be examined in the [sample implementation](https://github.com/infinum/android-halley/blob/main/sample/src/main/kotlin/com/infinum/halley/sample/ui/MainActivity.kt). + +_Halley_ Retrofit converter factory works as a standalone factory or together with Kotlin Coroutines, RxJava1, RxJava2 and RxJava3 +factories. +Various use cases can be examined in +the [sample implementation](https://github.com/infinum/android-halley/blob/main/sample/src/main/kotlin/com/infinum/halley/sample/ui/MainActivity.kt). + ### Ktor + ```kotlin HttpClient(CIO) { defaultRequest { @@ -370,10 +428,25 @@ suspend fun profileWithOptions(): ProfileResource = ) }.body() ``` -An example of a Ktor client can be examined [here](https://github.com/infinum/android-halley/blob/main/sample/src/main/kotlin/com/infinum/halley/sample/mock/client/SampleKtor.kt). + +An example of a Ktor client can be +examined [here](https://github.com/infinum/android-halley/blob/main/sample/src/main/kotlin/com/infinum/halley/sample/mock/client/SampleKtor.kt). + ## Requirements + _Halley_ is written entirely in Kotlin, for Kotlin models and projects. +## Contributing + +We believe that the community can help us improve and build better a product. +Please refer to our [contributing guide](CONTRIBUTING.md) to learn about the types of contributions we accept and the process for submitting +them. + +To ensure that our community remains respectful and professional, we defined a [code of conduct](CODE_OF_CONDUCT.md) that we expect all +contributors to follow. + +We appreciate your interest and look forward to your contributions. + ## License ``` diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..41d9f90 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,23 @@ +# Security + +## Reporting security issues + +At Infinum we are committed to ensuring the security of our software. If you have discovered a security vulnerability or have concerns +regarding the security of our project, we encourage you to report it to us in a responsible manner. + +If you discover a security vulnerability, please report it to us by emailing us at opensource@infinum.com. We will review your report, and +if the issue is confirmed, we will work to resolve the issue as soon as possible and coordinate the release of a security patch. + +## Responsible disclosure + +We request that you practice responsible disclosure by allowing us time to investigate and address any reported vulnerabilities before +making them public. We believe this approach helps protect our users and provides a better outcome for everyone involved. + +## Preferred languages + +We prefer all communication to be in English. + +## Contributions + +We greatly appreciate your help in keeping Infinum projects secure. Your efforts contribute to the ongoing improvement of our project's +security.