Kosrat

Flutter Ship 01: Git & GitHub Workflow

Sun, 20 Jul 2025 00:00:00 GMT

:::note[Updated] This post has been updated at 2 September 2025 with improved Git hook and PR Checks configurations. :::

Overview

More than two decades ago, Git emerged as a version control system (VCS) to facilitate teamwork and track changes in a version history. Nowadays, Git is an essential tool for software developers, especially for those working in a team. Complementing Git, platforms like GitHub provide hosting for Git repositories, enabling collaboration and sharing.

In this post, I will show you how to setup a production-ready Git & GitHub workflow for your project. As you may know, this article is a part of the Flutter Ship series, which guides you in shipping a production-ready Flutter app. However, these principles can be applied to any language or framework.

By the end of this article, you will learn the following:

How to implement a simple but effective branching strategy.
How to adopt a commit message standard for a clean history and automated changelogs.
How to automatically generate and manage project changelogs.
How to use Git hooks to automate local checks, like formating & linting files, linting commits, and running tests.
How to implement a GitHub PR Checks with GitHub Actions to automate your workflow.

If this sounds like what you're looking for, let's dive in!

Branch Strategy

A clear branching strategy is essential for any software project to prevent the chaos of direct commits to the main branch. Working directly on main can lead to frequent merge conflicts, broken builds, and lost code, especially in a team setting.

The solution is to use short-lived branches for every new piece of work, whether it's a feature, bugfix, or chore. While there are many branching strategies, I recommend a strategy based on the popular and straightforward GitHub Flow. It's simple to understand, promotes continuous delivery, and works exceptionally well for most projects.

The core idea is illustrated below:

Branch Types Explained

Main Branch (main): This is the stable branch that always reflects the latest production-ready state of your project. All releases and deployments are made from here.
Feature branches (feature-* or task-id-*): Used for developing new features, enhancements, bug fixings or tasks. If you use a task management tool (like Jira), you can integrate with it and name your branch after the task or ticket ID (e.g., ab-123-add-login). Each feature/task branch is short-lived and merged back into main via a pull request after review and testing.

This model also supports different development environments with ease. When you complete a feature or task, you open a pull request (PR). You can configure a GitHub Action (or any other CI/CD service) to run tests and automate the generation of APKs for Android and IPAs for iOS, and distribute them to testers or users via your chosen platforms. I’ll cover Flutter Continuous Delivery (CD) in detail in a future article.

:::tip[Git & Github Cheat Sheet] I assume you already know the basics of Git and GitHub, so I won’t include basic Git commands here. If you need a refresher, check out my Git & GitHub Cheatsheet article. :::

:::important[Git Merge Recommendation] If you merge branches locally, merge --no-ff is highly recommended. The --no-ff flag causes the merge to always create a new commit object, even if the merge could be performed with a fast-forward. This avoids losing information about the historical existence of a feature branch and groups all commits that together added the feature. :::

Commit Messages

Commit messages are your working history. While the probability of reading them is low, they are still valuable for maintaining a good commit history and understanding changes later on. At least once in a while, you need to read the history to get more details about an emerging issue. Furthermore, in most software projects, the changelog will be generated based on those commit messages to show the release changes between versions. So what could you find or generate if you have the following history?

* 4dcd0dc fix color
* 1e0acd7 fix issue
* 897cab6 Merge branch 'add-comment'
|\  
| * 7b2c3f3 integration
|/  
* 3d0b48d add feature
* 7287225 updated
* 1405829 update post
* dba0ea9 add post

To have team-level agreed standards for git commit messages, I highly recommend following Conventional Commits.

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Check out the following example that uses conventional commit messages, which are much easier to understand and allow you to easily generate changelogs:

* 4dcd0dc Update themeColor fixed property to true
* 1e0acd7 fix(comment): Update check script to include biome CI
* 897cab6 Merge branch 'add-comment'
|\  
| * 7b2c3f3 feat(comment): Integrate Giscus for comments and add styles
|/  
* 8cbd821 fix(dependencies): Update astro and biome versions in pnpm-lock.yaml
* 3d0b48d feat: Add support for rendering mermaid codes in the markdown files
* 7287225 ci: Update code quality job
* 1405829 refactor(post): Update muslim data post and released
* dba0ea9 feat(post): Add the first draft of muslim data post
* 31a1ef8 build: Remove astro compress

:::tip[Commit Structure] I highly recommend you to read the Conventional Commits documentation to get more information about the commit structure like type, scope, description, body, footer, and breaking changes. :::

AI-Generated Commit Messages

There are many tools that can help you write better conventional commits, and there are also AI tools to generate them. I used to test various tools to create commit messages, but recently I started using GitHub Copilot to generate conventional commit messages. By default, Copilot doesn't generate conventional commit messages, so we need to set a custom prompt in the settings.

VSCode Copilot Configuration for Commit Messages

If you're using VS Code with workspace-based settings, you can find the settings file at your-project > .vscode > settings.json.

For user-based settings, navigate to: Settings > Extensions > GitHub Copilot Chat > Commit Message Generation as attached below:

After you find the settings, add the following prompt to generate conventional commit messages:

// ...existing settings

"github.copilot.chat.commitMessageGeneration.instructions": [  
  {
    "text": "Generate a commit message that MUST follow the Conventional Commits format (feat, fix, docs, style, refactor, test, perf, build, ci, chore, revert). Include a brief description of the change in the subject line (under 72 characters) and a summarized explanation in the body, if necessary. Separate the subject and body with a blank line. Example: 'feat(auth): Add forgot password functionality to the login screen' or 'fix(products): Fix date format in the product list'."
  }
]

// ...existing settings

You can update the above prompt based on your needs. Now you can generate it with one click! 🎉

:::warning[Always Review AI Suggestions] AI-generated messages are a helpful starting point, but they aren't always perfect. Always review and refine the message for accuracy and clarity before committing. :::

Alternative Tools

Besides GitHub Copilot, here are other popular tools for conventional commits:

Commitizen: Interactive CLI tool that helps you to create conventional commits, auto bump versions and auto changelog generation.
Conventional Commits VS Code Extension: GUI helper for VS Code users.
Cocogitto: The Conventional Commits toolbox.
AI Commits: A CLI that writes your git commit messages for you with AI.
More: You can find more on the conventional commits about page.

Changelog

A CHANGELOG.md is a way to tell your consumers what has changed between versions. One of the most effective ways to do this is to generate it based on your git commit messages, which contain all your change history. There are many tools for generating changelogs, but one of my favorite tools is Git Cliff, which is a highly customizable changelog generator. It only takes three simple steps from installation to generation, as explained below:

Setup Git Cliff

Installation: It supports most package managers, so you can find your preferred one here. I use macOS, so I installed it via Homebrew:

brew install git-cliff

Initialization: After installation, navigate to your project and initialize it by running the following command, which creates a file named cliff.toml for further customization:

git-cliff --init

Generate: Finally, it's ready to generate a changelog by running the following command:

git-cliff -o CHANGELOG.md

That's all you need to generate a changelog! Here's an example that has been generated by Git Cliff. If you need any further customization, you can simply open and edit the cliff.toml file.

Common Customizations

I've picked some useful customizations from the cliff.toml to explain here:

1. Update the header & footer description

[changelog]
# template for the changelog header
header = """
# Changelog\n
All notable changes to this project will be documented in this file.\n
"""

# template for the changelog footer
footer = """
<!-- generated by git-cliff -->
"""

2. Support conventional and non-conventional commits

[git]
# parse the commits based on https://www.conventionalcommits.org
conventional_commits = true
# filter out the commits that are not conventional
filter_unconventional = true
# process each line of a commit as an individual commit
split_commits = false

3. Customize group ordering

# regex for parsing and grouping commits
commit_parsers = [                                            # Group Ordering
  { message = "^feat", group = "<!-- 0 -->🚀 Features" },     # 0 
  { message = "^fix", group = "<!-- 1 -->🐛 Bug Fixes" },     # 1
  { message = "^doc", group = "<!-- 3 -->📚 Documentation" }, # 3
  { message = "^perf", group = "<!-- 4 -->⚡ Performance" },   # 4
  { message = "^refactor", group = "<!-- 2 -->🚜 Refactor" }, # 2 <- ordered to 2
  { message = "^style", group = "<!-- 5 -->🎨 Styling" },
  { message = "^test", group = "<!-- 6 -->🧪 Testing" },
  # ...
]

4. Skip specific commit groups

# regex for parsing and grouping commits
commit_parsers = [
  # ...
  { message = "^perf", group = "<!-- 4 -->⚡ Performance" },
  { message = "^refactor", group = "<!-- 2 -->🚜 Refactor" },
  { message = "^style", group = "<!-- 5 -->🎨 Styling" },
  { message = "^test", group = "<!-- 6 -->🧪 Testing" },
  { message = "^chore\\(release\\)", skip = true }, # <-- skipped group
  # ...
]

5. Sort commits by date

# Organize commits within sections by oldest or newest order
sort_commits = "oldest"

For more advanced customizations, check out the Git Cliff documentation.

Git Hooks

Git hooks are scripts that automatically execute before or after specific Git actions, like committing, pushing, or merging. They allow you to customize Git's behavior, automate tasks, enforce policies, and streamline your workflow. read more

We can take advantage of Git hooks to automate the following tasks:

pre-commit: Before a commit is created.
- Apply dart fix to automatically fix issues.
- Apply dart format to reformat staged files.
- Run the Flutter linter to check for analysis issues.
commit-msg: After a commit message is written, but before the commit is created.
- Validate the commit message to ensure it follows the Conventional Commits standard.
pre-push: Before pushing code to a remote repository.
- Run all Flutter tests to prevent pushing broken code.

:::tip[Keep Git Hooks Fast and Reliable] Regarding the pre-push hook, if you have a large test suite that makes your git push command too slow, you can skip this hook and set up a PR check in your CI/CD pipeline as an alternative. :::

The Challenge with Manual Git Hooks

While you can set up hooks manually by placing executable scripts (e.g., pre-commit) in your project's .git/hooks/ directory, this approach has drawbacks. The .git directory is not version-controlled, so hooks are not shared across your team. Each developer must set them up manually, and keeping them updated is a maintenance burden. A Git hook manager solves these problems.

Git Hook Management with Lefthook

There are many hook managers available, but since there isn't one made specifically for Dart, we'll use a language-agnostic tool that works with any project: Lefthook. It's fast, powerful, and what I use in my own Flutter projects.

To get started, install Lefthook using your preferred package manager and run lefthook install in your project's root directory. This command creates a lefthook.yaml configuration file and installs the hooks into your .git directory.

:::tip I highly recommend reading the Lefthook documentation before proceeding. :::

Lefthook Configuration

Let's configure lefthook.yaml to run the tasks we outlined earlier.

pre-commit: Fix, Format, and Lint

This hook will run three commands in parallel on your staged Dart files before every commit.

pre-commit:
  parallel: true
  commands:
    auto-fix:
      run: dart fix --apply && git add {staged_files}
    pretty:
      glob: '*.dart'
      run: dart format {staged_files} && git add {staged_files}
    linter:
      run: flutter analyze {staged_files}

commit-msg:
  commands:
    validate:
      run: 'scripts/validate_commit_msg.sh'

pre-push:
  parallel: true
  commands:
    tests:
      run: flutter test

commit-msg: Validate Commit Message

Validating a commit message against the Conventional Commits specification is too complex for a single-line command, so we'll use an external script.

First, create the validation script in this path: scripts/validate_commit_msg.sh.

// filepath: scripts/validate_commit_msg.sh
#!/bin/bash

# Path to the commit message file
COMMIT_MSG_FILE=".git/COMMIT_EDITMSG"

# Check if the commit message file exists
if [ ! -f "$COMMIT_MSG_FILE" ]; then
  echo "Commit message file does not exist."
  exit 1
fi

# Read the commit message
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")

# Get the first line of the commit message
FIRST_LINE=$(echo "$COMMIT_MSG" | head -n 1)

# Define the Conventional Commits regex pattern
# Scope cannot contain spaces - only letters, numbers, hyphens, and underscores
PATTERN='^(feat|fix|build|chore|ci|docs|style|refactor|perf|test)(\([a-zA-Z0-9_-]+\))?(!)?: .+'

# Validate the commit message format
if [[ ! "$FIRST_LINE" =~ $PATTERN ]]; then
  echo "👎 Invalid commit message format."
  echo "Commit message should follow the Conventional Commits format:"
  echo "  <type>(<scope>): <description>"
  echo "  - type: feat, fix, build, chore, ci, docs, style, refactor, perf, test"
  echo "  - scope: optional, no spaces allowed (use hyphens or underscores instead)"
  echo "  - description: brief description"
  echo ""
  echo "Examples:"
  echo "  ✅ feat(user-auth): Add new authentication method"
  echo "  ✅ fix(api_client): Fix connection timeout issue" 
  echo "  ❌ fix(my feature): Fix some bug (scope contains spaces)"
  exit 1
fi

# Check if the first line is no more than 72 characters
if [ ${#FIRST_LINE} -gt 72 ]; then
  echo "👎 Commit message first line is too long (${#FIRST_LINE} characters)."
  echo "Please keep the first line to 72 characters or less."
  exit 1
fi

echo "👍 Valid commit message!"
exit 0

Next, make the script executable:

chmod +x scripts/validate_commit_msg.sh

Finally, add the validate-commit-msg script to your lefthook.yaml:

pre-commit:
  parallel: true
  commands:
    auto-fix:
      run: dart fix --apply && git add {staged_files}
    pretty:
      glob: '*.dart'
      run: dart format {staged_files} && git add {staged_files}
    linter:
      run: flutter analyze {staged_files}

commit-msg:
  commands:
    validate:
      run: 'scripts/validate_commit_msg.sh'

pre-push:
  parallel: true
  commands:
    tests:
      run: flutter test

pre-push: Run Tests

This hook runs all Flutter tests before you push. The push will be blocked if any tests fail.

pre-commit:
  parallel: true
  commands:
    auto-fix:
      run: dart fix --apply && git add {staged_files}
    pretty:
      glob: '*.dart'
      run: dart format {staged_files} && git add {staged_files}
    linter:
      run: flutter analyze {staged_files}

commit-msg:
  commands:
    validate:
      run: 'scripts/validate_commit_msg.sh'

pre-push:
  parallel: true
  commands:
    tests:
      run: flutter test

After you completed the configuration, you need to rerun the lefthook install to resync the git hooks. With this setup, your local development workflow is now automated to enforce code quality and consistency.

GitHub PR Checks

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production. read more

:::tip If you are new to CI/CD, I highly recommend reading the GitHub Actions documentation to get familiar with the core concepts. :::

Local Git hooks are great for immediate feedback, but they can be bypassed with a simple --no-verify flag. To guarantee that every commit merged into main follows the Conventional Commits standard, passes Flutter analyze and has no failing tests, we can set up a GitHub Actions workflow to run these validations automatically whenever a PR is opened against the main branch.

For the Flutter analyze and Flutter test steps, we need a common Flutter setup. To avoid duplicating this setup code, we can use GitHub Composite actions. Let's create a composite action to set up the Flutter environment. First, create a .github/actions/setup-flutter directory in the root of your project. Inside that directory, create a file named action.yaml with the following content:

// filepath: .github/actions/setup-flutter/action.yaml
name: "Setup Flutter"
description: "Setup Flutter with dependencies"
runs:
  using: "composite"
  steps:
    - name: Set up Flutter
      uses: subosito/flutter-action@v2
      with:
        channel: stable
        flutter-version-file: pubspec.yaml
    - name: Install dependencies
      run: flutter pub get
      shell: bash

Then let's create the PR checks workflow. First, create a .github/workflows directory in the root of your project. Inside that directory, create a file named pull_request.yaml with the following content:

// filepath: .github/workflows/pull_request.yaml
name: Flutter PR Checks

on:
  pull_request:
    branches:
      - main

jobs:
  commitlint:
    runs-on: ubuntu-latest
    name: Conventional Commitlint
    permissions:
      pull-requests: read
    steps:
      - name: Conventional Commitlint
        uses: opensource-nepal/commitlint@v1

  analyze:
    runs-on: ubuntu-latest
    name: Flutter Analyze
    needs: commitlint
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup Flutter
        uses: ./.github/actions/setup-flutter
      - name: Analyze code
        run: flutter analyze

  test:
    runs-on: ubuntu-latest
    name: Flutter Tests
    needs: analyze
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup Flutter
        uses: ./.github/actions/setup-flutter
      - name: Run tests
        run: flutter test

This workflow ensures that every pull request is automatically checked for code quality and passing tests before it can be merged, preventing broken code from reaching your main branch.

More Advanced Checks

While our current workflow is robust, you can further enhance code quality and security by enabling additional checks on GitHub.

1. Codecov Integration

Code coverage metrics help you understand how much of your codebase is tested. Codecov is a popular service that visualizes coverage reports, tracks changes over time, and provides PR feedback about coverage changes.

To integrate Codecov with your Flutter project, update the test job in your workflow:

  test:
    runs-on: ubuntu-latest
    name: Flutter Tests
    needs: analyze
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup Flutter
        uses: ./.github/actions/setup-flutter
      - name: Run tests with coverage
        run: flutter test --coverage
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          file: ./coverage/lcov.info
          fail_ci_if_error: false

After setting this up and connecting your repo to codecov.io, you'll get detailed coverage reports on each pull request, helping maintain or improve test coverage as your codebase evolves.

2. Automated Dependency Management with Dependabot

Keeping dependencies up-to-date is crucial for security and accessing new features. GitHub's Dependabot automates this process by:

Security Updates: Automatically creating pull requests to update vulnerable dependencies as soon as they are discovered.
Version Updates: Regularly checking for new versions of your dependencies and creating PRs to keep them current.

You can enable and configure Dependabot by creating a dependabot.yaml file in your .github directory. Here's a basic configuration for a Flutter project:

// filepath: .github/dependabot.yaml
version: 2
updates:
  - package-ecosystem: "pub"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "sunday"
      time: "00:00"
      timezone: "Asia/Baghdad"
    target-branch: "main"
    labels:
      - "dependencies"

This is a basic configuration example. For more advanced setups, you can optimize and customize Dependabot's behavior.

3. Implement Branch Protection Rules

Branch protection rules are a powerful GitHub feature that prevents direct pushes to important branches like main and enforces quality gates for pull requests. You can configure them in your repository settings under Settings > Branches > Add branch ruleset.

Key rules include:

Require status checks to pass: This is essential. It forces your Analyze & Test workflow (and any others) to succeed before a PR can be merged.
Require a pull request before merging: Disallows direct pushes to main and forces all changes to go through a review process.
Require signed commits: Ensures that commits are from a verified source, enhancing security.

By combining your CI workflow with these advanced checks, you create a nearly foolproof system for maintaining a high-quality, secure, and stable codebase.

Source Code

To see all the concepts from this article implemented in a real Flutter project, check out the Simple Todo App repository. Switch to the 01-git-github-workflow branch to see all in action.

# Clone and explore the implementation
git clone https://github.com/kosratdev/simple_todo.git
cd simple_todo
git checkout 01-git-github-workflow

# Install Lefthook and see the hooks in action
lefthook install

This repository serves as a practical reference for implementing everything we covered in this article. Feel free to fork it and use it as a starting point for your own Flutter projects!

We've covered a lot of ground in this article, from establishing a solid branching strategy to automating our entire workflow. By implementing GitHub Flow, Conventional Commits, automated changelogs with Git Cliff, local quality checks with Lefthook, and a basic CI pipeline with GitHub Actions, you've built a robust foundation for any Flutter project.

This setup isn't just about following rules; it's about creating a predictable, high-quality, and efficient development process. It ensures that every piece of code is consistent, tested, and ready for collaboration, freeing you up to focus on what matters most: building great features.

This is just the beginning of our journey. In the next article of the Flutter Ship series, we'll take this foundation and build upon it by setting up different flavors for different environments.

I hope this guide has been helpful. If you have any questions, suggestions, or want to share your own workflow tips, please leave a comment below.

Happy coding!🚀

Flutter Ship: Production Ready App

Mon, 19 May 2025 00:00:00 GMT

Overview

Welcome to Flutter Ship, a comprehensive series dedicated to guiding Flutter developers through the journey of building production-ready applications.

Flutter is a powerful cross-platform framework that enables developers to create beautiful, natively compiled applications for mobile, web, and desktop from a single codebase. With its expressive UI, fast development cycles, and growing community support, Flutter has established itself as a significant player in the app development ecosystem.

Whether you're building for startups or enterprise-level applications, Flutter provides the tools needed to deliver high-quality experiences across platforms. Companies like Google, Alibaba, and BMW have embraced Flutter for its performance benefits and development efficiency.

But what exactly makes an app "production-ready"? Is it just about having a functional UI, or does it cover aspects like maintenability, performance optimization, secure architecture, efficient state management, comprehensive testing, and seamless deployment strategies?

Through this Flutter Ship series, we'll explore the essential components that transform a basic app into a production-ready solution:

Flutter Ship 01: Git & GitHub Workflow
Flutter Ship 02: Set Up Environment (Flavors, App Icon, Splash Screen, and .env) --> (Planned)
Flutter Ship 03: Monitoring & Insights --> (May Be!)
Flutter Ship 04: Localization --> (May Be!)
Flutter Ship 05: App Architecture --> (May Be!)
Flutter Ship 06: More Sections

Follow along with this series to systematically elevate your Flutter projects from development experiments to polished, production-ready applications ready to delight users around the world.

Happy Coding!

Muslim Data: A library for Islamic Apps

Thu, 24 Apr 2025 00:00:00 GMT

Overview

Muslims perform prayers five times a day, and the prayer times vary from one location to another. These times are calculated based on the position of the sun relative to each specific location. The website praytimes.org explains the prayer time equations in detail and even provides implementations in several programming languages.

However, not all countries follow these calculated methods. For instance, in Iraq, fixed prayer times have been set by the Ministry of Awqaf, which differ from the auto-calculated ones. Because of this, many prayer time apps do not work correctly in our region.

Back in 2014, I noticed this gap in our local Muslim community — people couldn’t rely on the available prayer apps due to the use of fixed prayer times. To address this, I started developing a prayer app called MyPrayers. It offers both fixed and auto-calculated prayer times, along with other features such as Azkars, Qibla direction, the 99 Names of Allah, and more. The MyPrayers app is available on Google Play, AppGallery, and the App Store.

Since then, my goal has been to support developers who want to build Islamic apps by creating reusable and easy-to-integrate packages for Android, iOS, and Flutter. In 2020, I began working on an open-source library called Muslim Data, which provides all the core data needed for a prayer app. This includes accurate prayer times (both fixed and calculated), Azkars, Names of Allah, multi-language support and more — all accessible with just a few lines of code.

The Muslim Data project is available across all three platforms:

::github{repo="my-prayers/muslim-data-android"} ::github{repo="my-prayers/muslim-data-ios"} ::github{repo="my-prayers/muslim-data-flutter"}

The Muslim Data shipped with a prepopulated database for its core functionality and follows the repository design pattern which only exposes one class for providing data named MuslimRepository(). In this article, I’ll briefly showcase the functionality of the Muslim Data package. For more details, feel free to explore the repositories linked above.

Location Service

The Muslim Data package has prepopulated database contains some useful location functionalities that helps developers to build an app to not depend on the internet to find location or getting a location details by latitude and longitude. It provides Offline Location Search, Geocoding, and Reverse Geocoding and also the Location object has been used while getting a prayer time in the package.

Flutter Sample Usage

Search for a location: You can search for any cities or places around the world and this is useful when a user doesn't have internet connection or user's location is turned off so that you can search here:

Future<void> searchLocationExample() async {
  final muslimRepo = MuslimRepository();
  final locations = await muslimRepo.searchLocations(locationName: 'makka');

  print("Locations: $locations");
}

Geocode a location: Use geocoder method to find a location by country code and city name.

Future<void> geocodeLocationExample() async {
  final muslimRepo = MuslimRepository();
  final location = await muslimRepo.geocoder(
    countryCode: "GB",
    locationName: "London",
  );

  if (location != null) {
    print("Location: $location");
  } else {
    print("Location name cannot be geocoded");
  }
}

Reverse Geocode a location: Use reverseGeocoder method to find a location by latitude and longitude.

Future<void> reverseGeocode() async {
  final muslimRepo = MuslimRepository();
  final location = await muslimRepo.reverseGeocoder(
    latitude: 51.5074,
    longitude: -0.1278,
  );

  if (location != null) {
    print("Location: $location");
  } else {
    print("Location could not be reverse geocoded");
  }
}

Prayer Times

The location object holds hasFixedPrayerTime property to indicate whether use auto calculated prayer times or fetch it from the database. So by provide the (Location, PrayerAttribute, and Date) objects to the getPrayerTimes method, you can easily get prayer times of that location as shown below.

Flutter Sample Usage

Future<void> getPrayerTimesExample() async {
  final muslimRepo = MuslimRepository();

  // Create a PrayerAttribute object.
  final attribute = PrayerAttribute(
    calculationMethod: CalculationMethod.makkah,
    asrMethod: AsrMethod.shafii,
    higherLatitudeMethod: HigherLatitudeMethod.angleBased,
    offset: [0, 0, 0, 0, 0, 0],
  );

  // Assume that 'location' has been retrieved using one of the location methods above.

  final prayerTime = await muslimRepo.getPrayerTimes(
    location: location,  
    date: DateTime.now(),
    attribute: attribute,
  );

  if (prayerTime != null) {
    print("Prayer Times: $prayerTime");
  }
}

Azkars

As mentioned, the package has been shipped with prepopulated database that contains all Azkars from Hisnul Muslim book with its translation for the given language. Currently, it is available for these languages (en, ar, ckb, ckb_BADINI, fa, and ru).

Flutter Example Usage

Azkar Category: Get all azkar categories with its translation for the given language.

void getAzkarCategoriesExample() async {
  final muslimRepo = MuslimRepository();
  final categories = await muslimRepo.getAzkarCategories(language: Language.en);

  print("Azkar Categories: $categories");
}

Azkar Chapters:

Get azkar chapters with its translation for the given language.

void getAzkarChaptersExample() async {
  final muslimRepo = MuslimRepository();
  final categories = await muslimRepo.getAzkarChapters(language: Language.en);

  print("Azkar Chapters: $categories");
}

Get azkar chapters for a specific category with its translation for the given language.

void getAzkarChaptersExample() async {
  final muslimRepo = MuslimRepository();
  final categories = await muslimRepo.getAzkarChapters(
    language: Language.en,
    categoryId: 1,
  );

  print("Azkar Chapters: $categories");
}

Get azkar chapters by chapter ids. This method is particularly useful for implementing a favorites feature on azkar. By just saving the azkar ids, you can later retrieve the full details when needed using this method, simplifying management and synchronization of your favorite azkar entries.

void getAzkarChaptersExample() async {
  final muslimRepo = MuslimRepository();
  final categories = await muslimRepo.getAzkarChaptersByIds(
    language: Language.en,
    chapterIds: [12, 15],
  );

  print("Azkar Chapters: $categories");
}

Azkar Items: Get azkar items for a specific chapter and it is localized for the given language.

void getAzkarItemsExample() async {
  final muslimRepo = MuslimRepository();
  final categories = await muslimRepo.getAzkarItems(
    language: Language.en,
    chapterId: 1,
  );

  print("Azkar Items: $categories");
}

Names of Allah

Last but not least, the package provides the 99 names of Allah with its translation, and it is available for these languages (en, ar, ckb, ckb_BADINI, fa, and ru)

Flutter Example Usage

Future<void> getNamesOfAllah() async {
  final muslimRepo = MuslimRepository();
  final names = await muslimRepo.getNames(language: Language.en);
  print("Names of Allah: $names");
}

Contribution

We welcome contributions from developers of all skill levels! Whether you're improving documentation, fixing bugs, or suggesting new features, your input is invaluable. To get started, please review our guidelines on GitHub and feel free to open issues or submit pull requests.

Happy coding! 🚀

1M Crashes With Prepopulated Room Database

Thu, 04 Jul 2024 00:00:00 GMT

Overview

A decade ago, I noticed a gap in our local Muslim community. People couldn't use the available prayer apps because we used fixed prayer times instead of auto-calculated ones. So, I started developing a prayer app named MyPrayers that offers both fixed and auto-calculated prayer times, Azkars, Qibla direction, Names of Allah, and more. The MyPrayers app has been published on Google Play, AppGallery, and the App Store.

Since then, I've aimed to create an Android and iOS dependency to provide this data with just a few lines of code, supporting anyone who wants to build Muslim apps. In 2020, I started creating an open-source dependency for both Android and iOS platforms named muslim-data-android and muslim-data-ios, containing all the data that a prayer app needs.

Android Prepopulated Room Database

The muslim-data-android uses a local database for the fixed Prayer Times, Names of Allah, and Azkars. As part of the Android Jetpack libraries, Room is recommended to use local Android databases. It also supports prepopulated databases.

The Room persistence library provides an abstraction layer over SQLite to allow for more robust database access while harnessing the full power of SQLite.

From Room Documentation

After thoroughly reviewing the Room documentation and various published articles, I came across a useful code snippet for utilizing a prepopulated database with Room. This approach allows us to manage a local prepopulated database within your Android application.

@Database(
    entities = [...],
    version = 1,
)
abstract class MuslimDataDatabase : RoomDatabase() {
    internal abstract val muslimDataDao: MuslimDataDao

    companion object {

        @Volatile
        private var INSTANCE: MuslimDataDatabase? = null

        fun getInstance(context: Context): MuslimDataDatabase {
            synchronized(this) {
                var instance = INSTANCE
                if (instance == null) {
                    instance = Room.databaseBuilder(
                        context.applicationContext, MuslimDataDatabase::class.java,
                        "muslim_db.db"
                    )
                        .createFromAsset("database/muslim_db_v2.0.1.db")
                        .fallbackToDestructiveMigration()
                        .build()

                    INSTANCE = instance
                }

                return instance
            }
        }
    }
}

It is very simple and straight forward. It uses a singleton pattern to ensure only one instance of the database exists, using Room.databaseBuilder to build the database from an asset (muslim_db_v2.0.1.db) and apply a fallback strategy for destructive migrations. I’ve used it and tested on both different emulators and physical devices. All works as expected without any issues.

1M Crash Events 💣💥

After successfully publishing and integrating muslim-data-android in the MyPrayers app, I’ve received some unusual crashes in Firebase Crashlytics. These include SQLiteDiskIOException, SQLiteReadOnlyDatabaseException, and SQLiteException, all originating from the muslim-data-android dependency.

Sample of The Crash

Fatal Exception: android.database.sqlite.SQLiteDiskIOException: disk I/O error (code 1802 SQLITE_IOERR_FSTAT): , while compiling: PRAGMA journal_mode
at android.database.sqlite.SQLiteConnection.nativePrepareStatement(SQLiteConnection.java)
at android.database.sqlite.SQLiteConnection.acquirePreparedStatement(SQLiteConnection.java:1068)
at android.database.sqlite.SQLiteConnection.executeForString(SQLiteConnection.java:811)
at android.database.sqlite.SQLiteConnection.setJournalMode(SQLiteConnection.java:419)
at android.database.sqlite.SQLiteConnection.setJournalFromConfiguration(SQLiteConnection.java:339)
...
at android.database.sqlite.SQLiteDirectCursorDriver.query(SQLiteDirectCursorDriver.java:46)
at android.database.sqlite.SQLiteDatabase.rawQueryWithFactory(SQLiteDatabase.java:1718)
at android.database.sqlite.SQLiteDatabase.rawQueryWithFactory(SQLiteDatabase.java:1693)
at androidx.sqlite.db.framework.FrameworkSQLiteDatabase.query(FrameworkSQLiteDatabase.kt:156)
at androidx.room.RoomDatabase.query(RoomDatabase.kt:484)
at androidx.room.util.DBUtil.query(DBUtil.kt:75)
at dev.kosrat.muslimdata.database.MuslimDataDao_Impl.getPrayerTimes(MuslimDataDao_Impl.java:196)
at dev.kosrat.muslimdata.repository.MuslimRepository$getPrayerTimes$2.invokeSuspend(MuslimRepository.kt:56)
...

Furthermore, some users mentioned that when they close and reopen the app, it crashes. The tricky part is that I couldn’t reproduce it on my end. I’ve carefully reviewed and optimized all the database-related code, including data class entities, DAOs, queries, joins, etc. Despite publishing 3 versions, the issue persists and has reached 1 million crash events, as shown below.

After a long debugging and testing session, I finally discovered what was causing the issue 💪😎. It turns out it's all related to getting the database instance.

instance = Room.databaseBuilder(
            context.applicationContext,
            MuslimDataDatabase::class.java,
            "muslim_db.db"
            )
            .createFromAsset("database/muslim_db_v2.0.1.db")
            .fallbackToDestructiveMigration()
            .build()

This code snippet recreates the database from the asset every time the app is opened. This can lead to crashes if the database connection is already open. When you close the app, the database singleton instance will be destroyed, but the database connection may not be closed depending on the strategy of the Android OS. When you reopen the app, a crash can occur because it attempts to recreate an already open database.

The Right Way of Prepopulating Room Database

Unfortunately, none of the articles or Room documentation I’ve read describe this type of issue, even though they prefer to use it that way. Since the root cause of the issue has been detected, I’ve come up with a solution for a prepopulated Room database by using a condition to recreate the database based on its existence.

...
fun getInstance(context: Context): MuslimDataDatabase {
    synchronized(this) {
        var instance = INSTANCE
        if (instance == null) {
            val dbName = "muslim_db.db"
            val dbBuilder = Room.databaseBuilder(
                context.applicationContext,
                MuslimDataDatabase::class.java,
                dbName
            ).fallbackToDestructiveMigration()

            **// Copy database if it doesn't exist.
            val dbFile = context.getDatabasePath(dbName)
            if (!dbFile.exists()) {
                dbBuilder.createFromAsset("database/muslim_db_v2.1.0.db")
            }**

            instance = dbBuilder.build()

            INSTANCE = instance
        }
        return instance
    }
}
...

Now, this is the right way to use a prepopulated Room database 🎉🎊. It won't recreate the database from the asset every time the app is opened. When you get an instance from the database, it checks whether the database exists. If it does, it will connect to it; otherwise, it will create the database from the asset.

What about Database Migrations?

Room database migrations are another thing we need to consider once we have a Room database. The Room documentation explains the migrations in detail, as linked below, except for one scenario: What if I want to migrate my Room database using a prepopulated database from the asset?

Migrate your Room database | Android Developers

In our specific case, sometimes we need to update prayer times for a city, which involves modifying 366 records at once. It's not feasible to manage this task using normal migrations, so we must make changes directly to the prepopulated database and then recreate the Room database from the asset. We need to perform these tasks before getting or while getting the Room instance, similar to the initial database creation. To achieve this, we must identify any database version changes and then recreate it from the asset, as shown below.

...
if (!dbFile.exists() || isVersionChanged(context)) {
		dbBuilder.createFromAsset("database/muslim_db_v2.1.0.db")
}

The isVersionChanged method checks for changes in the database version to see if it has been updated. In Room database, versioning is used for migrations, so we can store the version in shared preferences and compare it each time we get a new instance. If it has changed, the method returns true; if not, it returns false. Additionally, we have used fallbackToDestructiveMigration and provided no migrations, so the Room database will be recreated from the asset in this case.

Here is the isVersionChanged method

private const val DB_VERSION = 1

@Database(
    entities = [...],
    version = DB_VERSION,
)
abstract class MuslimDataDatabase : RoomDatabase() {
    internal abstract val muslimDataDao: MuslimDataDao

    companion object {
				...
				...
		
				private fun **isVersionChanged**(context: Context): Boolean {
						val pref = PreferenceManager.getDefaultSharedPreferences(context)
				    val savedVersion = pref.getInt("DB_VERSION", 1)
				    if (savedVersion < DB_VERSION) {
				        pref.edit { putInt("DB_VERSION", DB_VERSION) }
				        return true
				    }
				    return false
				}
		}
}

All Together

The following snippet code shows the right way to use a prepopulated database from the asset and considering data migrations from the asset too.

private const val DB_VERSION = 1

@Database(
    entities = [...],
    version = DB_VERSION
)
abstract class MuslimDataDatabase : RoomDatabase() {
    internal abstract val muslimDataDao: MuslimDataDao

    companion object {

        @Volatile
        private var INSTANCE: MuslimDataDatabase? = null

        fun getInstance(context: Context): MuslimDataDatabase {
            synchronized(this) {
                var instance = INSTANCE
                if (instance == null) {
                    val dbName = "muslim_db.db"
                    val dbBuilder = Room.databaseBuilder(
                        context.applicationContext,
                        MuslimDataDatabase::class.java,
                        dbName
                    ).fallbackToDestructiveMigration()

                    val dbFile = context.getDatabasePath(dbName)
                    if (!dbFile.exists() || isVersionChanged(context)) {
                        dbBuilder.createFromAsset("database/muslim_db_v2.1.0.db")
                    }

                    instance = dbBuilder.build()

                    INSTANCE = instance
                }
                return instance
            }
        }

        private fun isVersionChanged(context: Context): Boolean {
						val pref = PreferenceManager.getDefaultSharedPreferences(context)
				    val savedVersion = pref.getInt("DB_VERSION", 1)
				    if (savedVersion < DB_VERSION) {
				        pref.edit { putInt("DB_VERSION", DB_VERSION) }
				        return true
				    }
				    return false
				}
    }
}

Finally we fixed the million crash events 🎉🎊💪

In wrapping up, using the Room with prepopulated databases in Android applications provides a great way to manage local databases with ease. By following the recommended approach and using the provided code snippets, developers can avoid the crashes that happened to me. Their apps will be safer, more efficient, and more reliable.

Happy Coding!

Git & GitHub Cheat Sheet

Tue, 28 May 2024 00:00:00 GMT

Having a Git and GitHub cheat sheet is highly beneficial, especially for those who frequently utilize these tools but may not remember every command. Git commands are crucial as they allow us to perform tasks like creating new repositories, making changes to existing projects, and viewing the history of our changes.

This cheat sheet is a handy reference guide for both beginners and experienced users. For beginners, it provides a simple and quick way to learn and use the most common commands. For experienced users, it serves as a quick reference for less frequently used commands or options. By having all the essential Git and GitHub commands in one place, productivity can be improved and common tasks can be performed faster 👌.

Git Configurations

# Sets up Git with your name
git config --global user.name "<Your-Full-Name>"

# Sets up Git with your email
git config --global user.email "<your-email-address>"

# Sign all commits by default 
git config --global commit.gpgsign true

# Globally disables fast-forward merging by default
git config --global merge.ff false

# Makes sure that Git output is colored
git config --global color.ui auto

# Displays the original state in a conflict
git config --global merge.conflictstyle diff3

# Configure text editor
git config --global core.editor "[code, atom, vim , nano, gedit] --wait"

# List all your configurations
git config --list

Git Startup Commands

# Create brand new repositories (repos) on your computer.
git init

# Copy existing repos from somewhere else to your local computer.
git clone {Repo URL}

# Check the status of a repo
git status

Git Log

# Display information about the existing commits.
git log

# Display commits per one line.
git log --oneline

# Display the files that have been changed in the commit.
git log --stat

# display the actual changes made to a file.
git log -p

# display the actual changes made to a commit.
git log -p {commit id}
# Or 
git show {commit id}

Git Add & Commit

# Add files from the working directory to the staging index.
git add

# add files
git add {file1} {file2} ...

# Add all files in the current directory
git add .

# Take files from the staging index and save them in the repository.
git commit

# Displays the difference between two versions of a file.
git diff

Refresh gitignore

# Unstage all files 
git rm -r --cached .

# Add them back in so that, the new .gitignore files will work.
git add .

Git Tag

# Add a signed tag
git tag -s v1.0

# Display all tags
git tag

# Delete a tag locally
git tag -d v1.0

# Delete a tag from the remote
git push --delete origin v1.0

# Adding a tag to a past commit
git tag -a v1.0 {commit id}

Git Branch

# List all branch names in the repository.
git branch

# Create new branch named sidebar.
git branch sidebar

# Change current branch to sidebar.
git checkout sidebar

# Create the alt-sidebar-loc branch and have it point to the commit with SHA 42a69f.
git branch alt-sidebar-loc 42a69f

# Delete a branch.
git branch -d sidebar

# Force delete a branch.
git branch -D sidebar

# see all branches' history at once.
git log --oneline --decorate --graph --all

# Create a branch and then checkout to the new branch.
git checkout -b fix-footer

Git Merge

# Merge sidebar into current branch without fast forwarding merge.
git merge --no-ff sidebar

Git Revert & Reset

# Alter the most-recent commit or add missing files
git commit --amend

# Reverses given commit
git revert {commit-id}

# Erases commits
git reset
git reset [tags] HEAD~1
tags:
--mix -> move commit to working directory
--soft -> move commit to staged index
--hard -> move commit to trash

GitHub

# Display full path to the remote repository.
git remote -v

# Create a connection from local repository to the remote repository.
git remote add origin {repository link}

# Send changes to the remote
git push

# Retrieve updates from the remote
git pull

That's all for this Git and GitHub cheat sheet! Keep this guide handy for quick reference while working on your projects. Remember, practice makes perfect, so keep using these commands until they become second nature. Happy coding! 👨‍💻👩‍💻