Merge remote-tracking branch 'lawnicons/develop' into shinka

.github/CONTRIBUTING.md

@@ -1,39 +1,72 @@
 # Lawnicons contributing guide
 Welcome to the Lawnicons contributing guide! This file will tell you what you need to know to contribute to Lawnicons.
 
-Before you start, please [fork](https://github.com/LawnchairLauncher/lawnicons/fork) the project and clone it to your machine. 
-
-Afterwards, you can either contribute icons or code.
+Before you start, please [fork](https://github.com/LawnchairLauncher/lawnicons/fork) the project and clone it to your machine. Afterwards, you can either contribute icons or code.
 
 ## Contributing icons
 To contribute icons, you only need an icon editor, a file explorer, a text editor, and a terminal window.
 
-### Icon guidelines
-See the below image for a summary of the icon guidelines. If you don't follow them, a team member will likely request changing the icons.
+For additional information on designing icons and samples, see [the Lawnicons Figma repository](https://www.figma.com/community/file/1227718471680779613) made by [Grabstertv](https://github.com/Grabstertv).
+
+### Artboard & Grid
+
+![](images/creating-icons-1-artboard.png)
+
+Each icon must fit the `160x160px` or `144x144px` (depending on the shape) content area size. It must not be smaller nor bigger than the specified sizes.
+
+### Foundation
+
+![](images/creating-icons-2-foundation.png)
+
+The stroke should be kept at `12px` in most cases. If `12px` is too thick, a stroke of `8px` can be used.
+For finer detail, a stroke of `6px` can be used. The standard widths are `6px`, `8px`, `10px`, `12px` and `14px`.
+
+In addition to the above, joins and start/end points must be rounded and the colour must be black `#000000`. 
+
+### Details
+
+![](images/creating-icons-3-detail.png)
+
+When designing icons, it's important to strike a balance with the level of detail. While some icons can be highly detailed, it's acceptable to remove certain details as long as the icon remains recognizable and stays true to its original concept. In some cases, you may need to completely rethink the icon to achieve a minimalist design.
 
-![](images/contributing-image-1.png)
+A great example of this is the Subway Surfers icon as seen in the example above. In Lawnicons, it was reimagined by using the graffiti-styled "S" from the game's logo instead of depicting the character, which would have required intricate shapes and varying stroke thicknesses.
 
-Each icon must fit the 160x160px or 144x144px (depending on the shape) content area size. It must not be smaller nor bigger than the specified sizes.
+![](images/creating-icons-3-balance.png)
 
-The default stroke should be kept at 12px. For finer detail, a stroke of 6px can be used. The standard widths are 6px, 8px, 10px, 12px and 14px.
+In contrary, it's also important to avoid too few details, as they may not be easily recognizable. Take the Headspace icon, for instance, which consists only of a circle. This may pose a problem for users since Lawnicons are not colored, and a simple circle on its own is not easily identifiable. Whenever possible, incorporate additional details that align with the app's design language. 
 
-In addition to the above, the icons must have an outlined (not filled) style, joins and start/end points must be rounded and the colour must be black `#000000`. If the original icon has a filled style, change the icon to adhere to the guidelines as seen below.
+In the Headspace example above, the circles usually have a face representing mood. By adding one of those faces to the circle, you can make the icon more recognizable.
 
-![](images/contributing-image-2.png)
+### Maintaining Consistency
 
-For additional information on designing icons, see [the Lawnicons Figma repository](https://www.figma.com/community/file/1227718471680779613) made by [Grabstertv](https://github.com/Grabstertv).
+![](images/creating-icons-4-outline.png)
 
-### Adding an icon to Lawnicons
+All icons must adhere to an outline (not filled) to maintain a consistent theme. However, fill can be used sparingly for small details that require minimal contrast or for elements that cannot be accurately recreated with an outline. 
+
+The key is to ensure that any filled elements do not overwhelm the overall icon design and align with the outlined style to create a harmonious and coherent icon set.
+
+### Maintaining Visual Balance
+
+![](images/creating-icons-5-balance.png)
+
+Sharp contrast occurs when there is a drastic change in stroke thickness without a smooth transition. For instance, using a `12px` stroke and suddenly decreasing it to `8px` creates an unbalanced visual effect in the final icon.
+
+To avoid sharp contrast, you can follow either of these two methods:
+
+1. **Uniform Stroke:** Instead of jumping between stroke thicknesses, use the next immediate increment in width. For example, transition from *12px* to *10px*.
+2. **Gradual Transition:** Rather than making a large jump, introduce an intermediate thickness. By going from `12px` to `10px` and then to `8px` you create a gradual transition or gradation. This approach helps maintain visual balance in your icon design.
+
+## Adding an icon to Lawnicons
 Here's how to add an icon to Lawnicons:
 
-#### Prerequesties
+### Prerequesties
 * Your icon in the SVG format, adhering to the [above guidelines](#icon-guidelines). The filename must use snake case (e.g. `files_by_google.svg`).
 * The package and activity name of the app.
 
-#### Via `icontool.py`
+### Via `icontool.py`
 Please check the [icon tool guide](/.github/icontool_guide.md) for more information.
 
-#### Via manual process
+### Via manual process
 1. Add the ready SVG to the `svgs` directory.
 
 1. Add a new line to `app/assets/appfilter.xml` (in alphabetical order, by the `name` attribute), and map the new icon to a package name and app's activity. For example:
@@ -50,8 +83,8 @@ Please check the [icon tool guide](/.github/icontool_guide.md) for more informat
 
 1. Done! You're ready to open a pull request. Please set `develop` as the base branch.
 
-### Finding the package and activity name of an app
-#### Using `adb`
+## Finding the package and activity name of an app
+### Using `adb`
 1. Connect your Android device or emulator to your laptop/desktop PC that has `adb` installed (see [this tutorial](https://www.xda-developers.com/install-adb-windows-macos-linux/) for more information) and open the app whose details you want to inspect, e.g. Telegram.
 1. Open a new Command Prompt or Terminal window and input `adb devices`.
 1. Finally, type the below-given command to get the information about the currently open application.
@@ -71,15 +104,15 @@ Please check the [icon tool guide](/.github/icontool_guide.md) for more informat
 
   The part before the `/` character in the above image, i.e. `org.telegram.messenger`, is the package name (`[PACKAGE_NAME]`). The part after it, i.e. `org.telegram.messenger.DefaultIcon`, is the activity name (`[APP_ACIVITY_NAME]`).
 
-#### Using 3rd-party apps
-##### IconRequest app
+### Using 3rd-party apps
+#### IconRequest app
 1. Download the [IconRequest app](https://github.com/Kaiserdragon2/IconRequest/releases). 
 2. Launch the app and click "REQUEST NEW" or "UPDATE EXISTING".
 3. Get the Activity details for each app.
 
 ![](images/contributing-image-4.png)
 
-##### Icon Pusher app
+#### Icon Pusher app
 1. Download the [Icon Pusher app](https://play.google.com/store/apps/details?id=dev.southpaw.iconpusher&hl=en&gl=US).
 2. Launch the app.
 3. Select the icon(s) you want to upload or select all by pressing the square in the top right. Then press "Send".
@@ -98,11 +131,7 @@ Afterwards, you can build the app by selecting the `appDebug` build variant.
 
 Here are a few contribution tips:
 - [The `app` module](https://github.com/LawnchairLauncher/lawnicons/tree/develop/app) contains most of Lawnicons' core code, while [the `svg-processor` module](https://github.com/LawnchairLauncher/lawnicons/tree/develop/svg-processor) contains the code that converts the SVGs inside the `svgs` folder into Android Drawables. Generally, the `app` module is where you should make most of your contributions.
-
 - You can use either Java or, preferably, Kotlin.
-
 - Make sure your code is logical and well formatted. If using Kotlin, see ["Coding conventions"](https://kotlinlang.org/docs/coding-conventions.html) in the Kotlin documentation.
-
 - Set `develop` as the base branch for pull requests.
-
 - Significant changes to the UI should be discussed on our [Lawnchair's Telegram group chat](https://t.me/lawnchairci). Generally, we want to keep things clean and simple.

.github/PULL_REQUEST_TEMPLATE/general_change.md

@@ -0,0 +1,17 @@
+## Description
+
+<!-- 
+Please include a summary of the change. Please also include relevant motivation and context.
+-->
+
+Fixes #(issue)
+
+<!--
+Note: You can remove the "Fixes #(issue)" if you don't plan on making this PR close an issue.
+-->
+
+## Type of change
+<!-- Replace :x: with :white_check_mark: to "check" the specified bullet -->
+
+:x: Bug fix (non-breaking change which fixes an issue)
+:x: General change (non-breaking change that doesn't fit the above categories, such as copyediting)

.github/PULL_REQUEST_TEMPLATE/icon_addition.md

@@ -0,0 +1,23 @@
+# Description
+<!-- Please provide a short summary of what icons you added, changed, or linked
+-->
+
+## Icons addition information
+<!-- Please specify if you added an icon that was requested in the icon request form, as seen below -->
+### Icons added
+* App Name (`package.name`) - added from icon request form
+* App Name (`package.name`)
+* App Name (`package.name`)
+
+### Icons updated
+* App Name (`package.name`)
+* App Name (`package.name`)
+
+### Icons linked
+* App Name (linked `package.name` to `@drawable/package`)
+* App Name (linked `package.name` to `@drawable/package`)
+
+## Contributor's checklist
+- [ ] I have followed the [Lawnicons Guidelines](./github/CONTRIBUTING.md)
+- [ ] I have ensured that Lawnicons builds correctly
+- [ ] I am willing to make changes to my icons if someone suggests changes

.github/pull_request_template.md

@@ -1,36 +1,6 @@
-## Description
+<!-- Please select the the `Preview` tab -->
 
-<!-- 
-Please include a summary of the change. Please also include relevant motivation and context.
-
-If this PR is an icon addition one, please provide a short summary on what icons you added, changed, or linked
--->
-
-Fixes #(issue)
-
-<!--
-Note: You can remove the "Fixes #(issue)" if you don't plan on making this PR close an issue.
--->
-
-## Type of change
-<!-- Replace :x: with :white_check_mark: to "check" the specified bullet -->
-
-:x: Bug fix (non-breaking change which fixes an issue)
-:x: Icon addition (non-breaking change that adds/modifies Lawnicons's icons)
-:x: General change (non-breaking change that doesn't fit the above categories, such as copyediting)
-
-<!-- Erase the below text if you are not making an icon addition -->
-## Icons addition information
-<!-- Please specify if you added an icon that was requested in the icon request form, as seen below -->
-### Icons added
-* App Name (`package.name`) - added from icon request form
-* App Name (`package.name`)
-* App Name (`package.name`)
-
-### Icons updated
-* App Name (`package.name`)
-* App Name (`package.name`)
-
-### Icons linked
-* App Name (linked `package.name` to `@drawable/package`)
-* App Name (linked `package.name` to `@drawable/package`)
+Select the appropriate sub-template:
+* [**Icon addition**](?expand=1&template=icon_addition.md&labels=needs+review,icon+change)
+* [General or miscellaneous change](?expand=1&template=general_change.md)
+* *[Blank](?expand=1&body=+) (not recommended)*

.github/workflows/build_debug_apk.yml

@@ -35,7 +35,7 @@ jobs:
       - uses: actions/setup-java@v3
         with:
           distribution: 'zulu'
-          java-version: 19
+          java-version: 20
       - uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
@@ -59,9 +59,24 @@ jobs:
           name: Debug APK
           path: app/build/outputs/apk/app/debug/*.apk
 
+  check-style:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: true
+      - uses: actions/setup-java@v3
+        with:
+          distribution: 'zulu'
+          java-version: 20
+      - uses: gradle/gradle-build-action@v2
+        with:
+          gradle-home-cache-cleanup: true
+      - run: ./gradlew spotlessCheck
+
   send-notifications:
     runs-on: ubuntu-latest
-    needs: build-debug-apk
+    needs: [ build-debug-apk, check-style ]
     steps:
       - name: Check out repository
         uses: actions/checkout@v3

.github/workflows/build_release_apk.yml

@@ -18,7 +18,7 @@ jobs:
       - uses: actions/setup-java@v3
         with:
           distribution: 'zulu'
-          java-version: 19
+          java-version: 20
       - uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true