v8: Major improvements & 'flutter_map' v4 support (JaffaKetchup#114)

* Updated versioning throughout Reorganised internal errors Supported v8 of sharing module Improved stability * Added support for custom HTTP clients (JaffaKetchup#112) * Fix example application building * Fix example application building * Built Example Applications * Fixed bugs * Built Example Applications * Fixed bugs (JaffaKetchup#68 & JaffaKetchup#90) * Built Example Applications * Performance improvements Internal refactoring * Updated versioning Updated changelog * Built Example Applications * Updated issue templates Updated contributing guidelines * Fixed bugs within initialisation safety system * Built Example Applications * Updated Windows building configuration * Built Example Applications * Added eviction of failed tiles from `ImageCache` (JaffaKetchup#115) Refactored `bulkDownloader` in preparation for future works Added Android app signing to example Updated GitHub Actions workflow to improve stability * Removed Android app signing from example app * Fixed GitHub Actions workflow * Built Example Applications * Reimplemented bulk download system Fixed high memory usage when bulk downloading (JaffaKetchup#86) Improved bulk downloading performance Minor refactoring and bug fixes * Ignored false-positive lint * Built Example Applications * Fixed bulk downloading cancelling/ending system in non-buffered mode * Built Example Applications * Fixed bugs * Built Example Applications * Added status code check to bulk downloader Updated version, changelog, and readme * Built Example Applications * Improved stability of some synchronous methods * Minor improvements * Built Example Applications * Improved stability of `initialisation` method Improved efficiency of `TilesGenerator` isolates Fixed major bug Updated example application * Built Example Applications * Updated CHANGELOG and versioning Removed Ko-Fi sponsoring option due to GitHub Sponsors being preferable Removed deprecated methods and options from previous versions Minor improvements to `RootManagement.reset` method * Built Example Applications * Added support for 'flutter_map' v4 Updated CHANGELOG and version * Built Example Applications * Minor documentation improvements * Built Example Applications * Added support for Isar 3.1.0 Bug fixes * Built Example Applications * Updated dependencies Added more appropriate attribution * Built Example Applications * Increased memory efficiency during bulk downloading Bug fixes & performance improvements Minor refactoring * Built Example Applications * Prepare for v8 release Complete upgrade to flutter_map v4 * Bumped to v8.0.0 --------- Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: JaffaKetchup

.github/FUNDING.yml

@@ -1,2 +1 @@
-github: JaffaKetchup
-ko_fi: JaffaKetchup
+github: JaffaKetchup

.github/ISSUE_TEMPLATE/bug-report.yaml

@@ -8,59 +8,61 @@ body:
  value: "
  # Bug Report
 
- Thanks for taking the time to fill out this bug report! It helps us to improve the experience for you and other developers that may be facing a similar problem. We aim to respond to bug reports as soon as possible, but it may take longer to resolve this issue depending on its complexity and severity. To help us verify the issue quicker, please include as much information as you can.
+ Thanks for taking the time to fill out this bug report! To help us verify the issue quicker, please include as much information as you can.
+ 
+ 
+ ---
+ 
+ 
+ FMTC is a large, platform-dependent package, and there's only one person running manual tests on it before releases, so your support is appreciated.
+ 
+ > If you are using FMTC in a proprietary project, please read and understand [this important legal notice](https://fmtc.jaffaketchup.dev/#proprietary-licensing) on the topic of licensing. Please get in touch if you would like more information!
+ 
+ 
+ ---
+ 
+ 
+ Before reporting a bug, please:
+
+ * Check if there is already an open or closed issue that is similar to yours
+ 
+ * Ensure that your Flutter environment is correctly installed & set-up
+ 
+ * Ensure that this package, 'flutter_map', and any modules are correctly installed & set-up
+ 
+ 
+ ---
  "
- - type: markdown
- attributes:
- value: ---
  - type: textarea
- id: description
+ id: details
  attributes:
  label: What is the bug?
- description: What were you implementing when you found this issue? What happens when the bug triggers?
- validations:
- required: true
- - type: textarea
- id: expected-behaviour
- attributes:
- label: What is the expected behaviour?
- description: What do you think should have happened?
+ description: What were you implementing when you found this issue? What happens when the bug triggers? What do you think should have happened instead? Please include as much detail as possible, including screenshots and screen-recordings if you can.
  validations:
  required: true
  - type: textarea
  id: reproduce
  attributes:
- label: How can we reproduce this issue?
+ label: How can we reproduce it?
  description: |
- Please include a [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example) (preferable), otherwise detail the exact steps to reproduce this issue.
- If you do not include any information here, it will take longer for us to verify your issue.
+ Please include a fully formatted [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example) wrapped in a [Dart code block](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#syntax-highlighting), otherwise, detail the exact steps to reproduce this issue.
+ If you do not include any information here, it will take longer for us to verify your issue. 
+ validations:
+ required: true
  - type: textarea
  id: solution
  attributes:
  label: Do you have a potential solution?
- description: "If so, please detail it: it will make it quicker for us to fix the issue"
- - type: textarea
- id: additional-info
- attributes:
- label: Can you provide any other information?
- description: |
- Please attach any other logs, screenshots, or screen recordings.
- Is there anything else you'd like to say?
+ description: "If so, please detail it: it will make it quicker for us to fix the issue."
  - type: markdown
  attributes:
  value: ---
- - type: dropdown
+ - type: input
  id: platform
  attributes:
- label: Platforms Affected
- description: What platforms does this issue affect?
- multiple: true
- options:
- - Android
- - iOS
- - Windows
- - MacOS
- - Linux
+ label: Platforms
+ description: Please detail the devices and operating systems you can reproduce this bug on, separated by commas.
+ placeholder: eg. Android 13 (Samsung Galaxy S99), Windows 11 (x64)
  validations:
  required: true
  - type: dropdown
@@ -74,33 +76,4 @@ body:
  - "Erroneous: Prevents normal functioning and causes errors in the console"
  - "Fatal: Causes the application to crash"
  validations:
- required: true
- - type: dropdown
- id: frequency
- attributes:
- label: Frequency
- description: How often does this issue occur?
- options:
- - "Once: Occurred on a single occasion"
- - "Rarely: Occurs every so often"
- - "Often: Occurs more often than when it doesn't"
- - "Consistently: Always occurs at the same time and location"
- validations:
- required: true
- - type: markdown
- attributes:
- value: ---
- - type: checkboxes
- id: terms
- attributes:
- label: Requirements
- description: These are in place to prevent spam and unnecessary reports. Please read and understand them fully before posting.
- options:
- - label: I agree to follow this project's [Code of Conduct](https://github.com/jaffaketchup/flutter_map_tile_caching/blob/main/CODE_OF_CONDUCT.md)
- required: true
- - label: I have checked for known issues in the GitHub tracker and [on the docs site](https://fmtc.jaffaketchup.dev/known-issues-and-reporting#known-issues)
- required: true
- - label: I have completed the pre-report checks listed [on the docs site](https://fmtc.jaffaketchup.dev/known-issues-and-reporting#reporting-a-bug)
- required: true
- - label: If I am using FMTC in a proprietary project, I have read and understood [this important legal notice](https://fmtc.jaffaketchup.dev/#proprietary-licensing)
- required: true
+ required: true

.github/ISSUE_TEMPLATE/feature-request.yaml

@@ -8,11 +8,26 @@ body:
  value: "
  # Feature Request
 
- Thanks for taking the time to let us know what you want to see! It helps us to improve the experience for you and other developers that may be facing a similar problem. Unfortunately, response times for feature requests are longer than bug reports, as they are lower priority. If you want this functionality implemented quickly, please make a Pull Request to go alongside this feature request.
+ Thanks for taking the time to let us know what you want to see! 
+ Unfortunately, response times for feature requests are longer than bug reports, as they are lower priority. If you want this functionality implemented quickly, please make a Pull Request to go alongside this feature request.
+ 
+ > If you are using FMTC in a proprietary project, please read and understand [this important legal notice](https://fmtc.jaffaketchup.dev/#proprietary-licensing) on the topic of licensing. Please get in touch if you would like more information!
+ 
+ 
+ ---
+ 
+ 
+ Before requesting a feature, please:
+
+ * Check if there is already an open or closed issue that is similar to yours
+ 
+ * Ensure that you're using the latest version of FMTC and any modules
+ 
+ * Ensure that you've read the documentation thoroughly
+ 
+ 
+ ---
  "
- - type: markdown
- attributes:
- value: ---
  - type: textarea
  id: description
  attributes:
@@ -25,30 +40,14 @@ body:
  attributes:
  label: What other alternatives are available?
  description: Have you used any workarounds, for example?
- - type: textarea
- id: additional-info
- attributes:
- label: Can you provide any other information?
- description: |
- Please attach any other logs, screenshots, or screen recordings.
- Is there anything else you'd like to say?
  - type: markdown
  attributes:
  value: ---
- - type: dropdown
- id: platform
+ - type: textarea
+ id: additional-info
  attributes:
- label: Platforms Affected
- description: What platforms does this issue affect?
- multiple: true
- options:
- - Android
- - iOS
- - Windows
- - MacOS
- - Linux
- validations:
- required: true
+ label: Can you provide any other information?
+ description: Is there anything else you'd like to say?
  - type: dropdown
  id: severity
  attributes:
@@ -60,20 +59,3 @@ body:
  - "Obtrusive: No workarounds are available, and this is essential to me"
  validations:
  required: true
- - type: markdown
- attributes:
- value: ---
- - type: checkboxes
- id: terms
- attributes:
- label: Requirements
- description: These are in place to prevent spam. Please read and understand them fully before posting.
- options:
- - label: I agree to follow this project's [Code of Conduct](https://github.com/jaffaketchup/flutter_map_tile_caching/blob/main/CODE_OF_CONDUCT.md)
- required: true
- - label: I have checked for similar feature requests which may be duplicates
- required: true
- - label: I am using the [latest stable version](https://pub.dev/packages/flutter_map_tile_caching) of this package
- required: true
- - label: If I am using FMTC in a proprietary project, I have read and understood [this important legal notice](https://fmtc.jaffaketchup.dev/#proprietary-licensing)
- required: true

.github/workflows/main.yml

@@ -36,8 +36,6 @@ jobs:
  uses: subosito/flutter-action@v2
  with:
  channel: "stable"
- - name: Ensure Correct Flutter Installation
- run: flutter --version
  - name: Get All Dependencies
  run: flutter pub get
  - name: Check Formatting
@@ -65,20 +63,18 @@ jobs:
  uses: subosito/flutter-action@v2
  with:
  channel: "stable"
- - name: Ensure Correct Flutter Installation
- run: flutter --version
- - name: Ensure Clean Flutter Environment
- run: flutter clean
  - name: Remove Existing Prebuilt Applications
  run: Remove-Item "prebuiltExampleApplications" -Recurse -ErrorAction Ignore
  working-directory: .
  - name: Create Prebuilt Applications (Output) Directory
  run: md prebuiltExampleApplications
  working-directory: .
+ - name: Get All Dependencies
+ run: flutter pub get
  - name: Build Android Application
- run: flutter build apk --split-per-abi --obfuscate --split-debug-info=/symbols
+ run: flutter build apk --obfuscate --split-debug-info=/symbols
  - name: Move Android Application To Output Directory
- run: move "example\build\app\outputs\flutter-apk\app-armeabi-v7a-release.apk" "prebuiltExampleApplications\AndroidApplication.apk"
+ run: move "example\build\app\outputs\flutter-apk\app-release.apk" "prebuiltExampleApplications\AndroidApplication.apk"
  working-directory: .
  - name: Build Windows Application
  run: flutter build windows --obfuscate --split-debug-info=/symbols

.pubignore

@@ -0,0 +1 @@
+prebuiltExampleApplications/

CHANGELOG.md

@@ -13,7 +13,25 @@ Many thanks to my sponsors, no matter how much or how little they donated. Spons
 
 # Changelog
 
-## [7.2.0] - 2023/03/XX
+## [8.0.0] - 2023/XX/XX
+
+* Bulk downloading has been rewritten to use a new implementation that generates tile coordinates at the same time as downloading tiles
+ * `check`ing the number of tiles in a region now uses a significantly faster and more efficient implementation
+ * Starting a download no longer causes significant memory bloat, which could crash the app on large regions
+ * Starting a download is now much quicker and closer to constant time, as tile coordinates don't need to be pre-generated
+ * Cancelling a download no longer causes many `QueueCancelledException`s to be thrown, which could crash the app
+ * Removed reliance on 'queue' dependency in order to squeeze as much speed as possible out of the new implementation
+* Other improvements
+ * `initialise` now automatically renames databases if their filename ID doesn't match their name hash
+ * `initialise` can now throw a more useful `FMTCInitialisationException` with improved clarity
+ * Methods that require a valid store descriptor object to be present now throw `FMTCDamagedStoreException` if it is not present
+* Other bug fixes
+ * `FMTCImageProvider`'s oldest tile deleter & bulk downloading now respects custom root directories
+ * `FMTCImageProvider` now evicts failed images from Flutter's `ImageCache` to prevent errors
+* Added support for custom `HttpClient`s/`BaseClient`s
+* Added support for Isar v3.1 (bug fixes & stability improvements)
+
+## [7.2.0] - 2023/03/03
 
 * Stability improvements
  * Starting multiple downloads no longer causes `LateInitializationErrors`

CONTRIBUTING.md

@@ -1,17 +1,23 @@
 # Contributing
 
-*Please note we have a code of conduct, please follow it in all your interactions with this project.*
+## Reporting A Bug
 
-When contributing to this repository, please first discuss the change you wish to make via any one of the following:
+FMTC is a large, platform-dependent package, and there's only one person running manual tests on it before releases, so there's a decent chance that a bug you've found is actually a bug. Reporting it is always appreciated!
 
-- A feature request issue (preferred)
-- A ping to '@JaffaKetchup' on the flutter_map Discord server plugin channel (preferred for small changes)
-- An email to github@jaffaketchup.dev (last resort)
+Before reporting a bug, please:
 
-You may then submit a pull request, conforming to the following basic rules:
+* Check if there is already an open or closed issue that is similar to yours
+* Ensure that your Flutter environment is correctly installed & set-up
+* Ensure that this package, 'flutter_map', and any modules are correctly installed & set-up
 
-- Try to ensure code is concise, but well documentated and explained within the code
-- Try to keep to a similar coding style as I have used
-- You must not change the linting rules
+## Contributing Code
 
-Thanks for you contribution, it's greatly appriciated!
+Contributors are always welcome, and support is always greatly appreciated! Before opening a Pull Request, however, please open a feature request or bug report to link the PR to.
+
+When submitting code, please:
+
+* Keep code concise and in a similar style to surrounding code
+* Document all public APIs in detail and with correct grammar
+* Use the included linting rules
+* Update the example application to appropriately consume any public API changes
+* Avoid incrementing this package's version number or changelog

README.md

@@ -25,9 +25,7 @@ Many thanks for any amount you can spare, it means a lot to me!
 
 You can read more about me and what I do on my [GitHub Sponsors](https://github.com/sponsors/JaffaKetchup) page, where you can donate as well.
 
-[![Sponsor Me Via GitHub Sponsors](GitHubSponsorsImage.jpg)](https://github.com/sponsors/JaffaKetchup)
-
-Alternatively, if you prefer not to use GitHub Sponsors, please feel free to use my [Ko-fi](https://ko-fi.com/jaffaketchup). Note that the PayPal backend will take a small percentage amount of donations made through this method.
+[![Sponsor Me Via GitHub Sponsors](https://github.com/JaffaKetchup/flutter_map_tile_caching/blob/main/GitHubSponsorsImage.jpg)](https://github.com/sponsors/JaffaKetchup)
 
 ## (Proprietary) Licensing
 
@@ -43,4 +41,4 @@ However, I am willing to sell alternative (proprietary) licenses on a case-by-ca
 
 I learnt (and am still learning) to code with free, open-source software due to my age and lack of money, and for that reason, I believe in promoting open-source wherever possible to give equal opportunities to everybody, no matter their age or financial position. I'm not sure it's fair for commercial proprietary applications to use software made by people for free out of generosity. On the other hand, I am also trying to make a small amount of money from my projects, by donations or by selling licenses. And I recognise that commercial businesses may want to use my projects for their own proprietary applications.
 
-Therefore, if you would like a license to use this software within a proprietary, I am willing to sell a (preferably yearly or usage based) license for a reasonable price. If this seems like what you want/need, please do not hesitate to get in touch via [fmtc@jaffaketchup.com](mailto:fmtc@jaffaketchup.com).
+Therefore, if you would like a license to use this software within a proprietary, I am willing to sell a (preferably yearly or usage based) license for a reasonable price. If this seems like what you want/need, please do not hesitate to get in touch via [fmtc@jaffaketchup.dev](mailto:fmtc@jaffaketchup.dev).

buildAndServeDocs.bat

@@ -4,7 +4,7 @@
 # This file should be version controlled.
 
 version:
- revision: cd41fdd495f6944ecd3506c21e94c6567b073278
+ revision: f72efea43c3013323d1b95cff571f3c1caa37583
  channel: stable
 
 project_type: app
@@ -13,11 +13,11 @@ project_type: app
 migration:
  platforms:
  - platform: root
- create_revision: cd41fdd495f6944ecd3506c21e94c6567b073278
- base_revision: cd41fdd495f6944ecd3506c21e94c6567b073278
+ create_revision: f72efea43c3013323d1b95cff571f3c1caa37583
+ base_revision: f72efea43c3013323d1b95cff571f3c1caa37583
  - platform: windows
- create_revision: cd41fdd495f6944ecd3506c21e94c6567b073278
- base_revision: cd41fdd495f6944ecd3506c21e94c6567b073278
+ create_revision: f72efea43c3013323d1b95cff571f3c1caa37583
+ base_revision: f72efea43c3013323d1b95cff571f3c1caa37583
 
  # User provided section