development.md

Development Instructions

This document outlines how to set up your development environment for Gibsonify, run the app, and also explains the app structure, how to contribute, and how to build and release the app.

Dev Environment Set up

For development, it is recommended to run the app on an Android emulator using a Flutter SDK. You can run the app using the SDK from the command line, or from an IDE such as VSCode/VSCodium (with the Flutter extension) or Android Studio.

Currently, it is attempted to carry out development on the latest Flutter stable SDK release. However, due to the rapid development of Flutter, this might not keep up in the future, which is why the last tested SDK version is noted in the fvm_config.json file within the .fvm directory.

Developing can be done using the Flutter SDK, which can be installed from here, by following all the commands below while omitting fvm from them e.g. running flutter doctor instead of fvm flutter doctor (and also skipping fvm install). All commands below assume the use of a unix-like system.

If the latest stable Flutter SDK doesn't work, it is recommended to use Flutter Version Management (fvm) with the Flutter SDK version specified in fvm_config.json. First, install fvm using the official instructions. Then, after cloning this project and navigating into its directory in terminal, install the required Flutter SDK version

fvm install

This should automatically install the correct Flutter version via fvm, which you can check by running fvm doctor.

After installing, you can optionally disable Flutter and Dart analytics

fvm flutter config --no-analytics && fvm dart --disable-analytics

Afterwards, make sure to correctly set up the Android toolchain, Android studio, or anything else that will be missing until Flutter stops complaining after running doctor

fvm flutter doctor

Running

Before running Gibsonify for the first time, fetch all the dependencies

fvm flutter pub get

You can run the app in debug mode from Android Studio, from VSCode/VSCodium by pressing F5 or from the terminal with

fvm flutter run

App structure

Gibsonify uses a feature-driven directory structure, where the app is broken down into multiple self-contained features, each having its own subdirectory in the lib directory e.g. collection or recipe. Each feature is acessible in other parts of the app by importing its barrel file (e.g. collection.dart), for example

import 'package:gibsonify/navigation/navigation.dart';

For state management, Gibsonify uses the BLoC pattern with the help of the flutter_bloc library. Each feature has one BLoC, located in the bloc subdirectory of each feature, along with its states and events. To easily implement new BLoCs, the BLoC extension for VSCode/VSCodium or Android Studio is handy.

The underlying classes used by the BLoC of each feature are in the models subdirectory of each feature, and the UI of the feature is in the view subdirectory, utilizing modular widgets in the widgets subdirectory.

Contributing

This project follows a simplified gitflow branch structure and Conventional Commits. The main branch is main, which contains both the active development source code and the source of stable release versions of Gibsonify. These stable versions are in commits with tags containing the given version number, e.g. 1.0.0. The main branch shouldn't be directly commited to, as commits should be made into branches branched out of the main branch, e.g. feat/add-awesome-feature. These are then merged to main after passing tests and being approved.

To contribute, open a pull request (PR) from your branch to the main branch, naming your PR according to Conventional Commits, e.g. feat: add awesome feature. For major changes, please open an issue first to discuss what you would like to change.

Your commits should also follow Conventional Commits, and it is recommended to use Commitizen, which creates conventional commits for you using cz c. The compliance of each commit can be automatically checked by pre-commit, by installing it as outlined here, and installing the commitizen hook

pre-commit install --hook-type commit-msg

All changes are documented in CHANGELOG.md, which is generated using commitizen as well. After a PR is approved, run the following to update the changelog

cz changelog

This should be then commited as docs(changelog): update, and the PR should be merged to main using a merge commit with a message corresponding to the PR name (e.g. feat: add awesome feature). If the commits in the PR don't follow conventional commits, do a squash and merge to preserve conventional commits in main.

Releasing

Before making a new release version, create a chore/release-x.y.z branch from the main branch, implement any pre-release changes, and open a PR named chore: release x.y.z, where x.y.z can be deduced by running cz bump --dry-run and observing the printed version. This is an automatically generated Semantic Version from conventional commits.

After implementing all changes and having the PR approved, update the version in cz.yaml and pubspec.yaml and also update the changelog all in a single command by running

cz bump

This will update these three files and create a commit chore: bump version a.b.c to x.y.z, along with an annotated git tag x.y.z. The PR should be then merged into main with the merge commit message chore: release x.y.z.

To release a signed version of the Gibsonify android app via an apk, you need to have the Gibsonify java signing key on your machine. This key was generated using instructions found here and here on 30 January 2022 and has the id 7c909176. You then need to have a key.properties file in the android subdirectory of Gibsonify, which includes the path and password to the key. Only trusted developers should be able to build signed releases of Gibsonify, and this key should only be circulated amongst them.

Having satisfied this, an Android apk can be generated by running

flutter build apk --release

This will output app-release.apk to gibsonify/build/app/outputs/apk/release. Do not rename this file as this would break download links from GitHub releases. This is a fat apk that should run on most Android architectures.

The SHA256 checksum for the app-release.apk file should then be generated by running shasum -a 256 app-release.apk > app-release-checksum.txt on Mac or sha256sum release.apk > app-release-checksum.txt on Linux. These files can then also be signed by the PGP key of the developer making the release.

Finally, a GitHub release from the final commit with the a.b.c tag in the main branch should be made, and the app-release.apk and app-release-checksum.txt files uploaded (and possibly their PGP signatures). The changelog from previous version should be included in the GitHub release text field.