Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
245 lines (152 loc) · 9.38 KB

CONTRIBUTING.md

File metadata and controls

245 lines (152 loc) · 9.38 KB

Contributing to Sharezone

Note: The CONTRIBUTING.md is in the process of being made. See #28 for the missing sections.

Welcome

We love that you are interested in contributing to Sharezone 💙 There are many ways to contribute, and we appreciate all of them. This document gives a rough overview of how you can contribute to Sharezone and which steps you need to follow to set up the development environment.

If you have any questions, please join our Discord.

How to set up your development environment

If you would like to contribute to our code, please follow the introduction to set up your development environment.

Operating system

tl;dr: We recommend macOS.

You can use the operating system you like. But we recommend to use macOS because you might have some issues with other operating systems.

Known issues:

  • Golden tests are only passing with macOS
  • The Sharezone CLI (used for development) only officially supports macOS and Windows (should also work with other operating systems, but might cause problems in some cases)

If you discover unknown issues that are related to the operating system, please submit a new ticket on GitHub.

IDE

tl;dr: We recommend VS Code.

Flutter supports IDE support for VS Code and Android Studio. We support only VS Code. This doesn't mean you can't use other IDEs, like Android Studio. But you might need to set up more configuration steps that aren't documented by us (like launch configurations).

We added some files from the .vscode folder to this repository. This ensures that all VS Code users have the same VS Code settings (like formatting, launch configurations, etc.) for this repository.

Flutter

Our Sharezone app uses the Flutter framework. In order to run tests, compile the app, etc. you need to setup Flutter.

Please follow the official documentation: Install Flutter

Java

To build the Android app, you must have Java 17 installed. You can download Java 17 from the official website.

In case you don't want to build the Android app, you can skip this step.

Sharezone CLI

We have written our own CLI to manage our repository. Common use cases for the CLI are:

  • Analyze all packages inside this repository (sz analyze)
  • Clean up files of failed golden tests (sz clean-goldens)
  • Format all packages inside this repository (sz format)
  • Add license headers to all files (sz lh add)
  • Generate localization files (sz l10n generate)
  • Run all tests for all packages inside this repository (sz test)

macOS

Execute the following steps to install the Sharezone CLI:

  1. Clone this repository
  2. Navigate to the repository (cd sharezone-app)
  3. Run dart pub get -C tools/sz_repo_cli
  4. Add the ./bin to your environment variables
  5. Restart your terminal

You should now be able to run sz or sharezone in your terminal.

Windows

Execute the following steps to install the Sharezone CLI:

  1. Clone this repository
  2. Navigate to the repository (cd sharezone-app)
  3. Run dart pub get -C tools/sz_repo_cli
  4. Add the ./bin to your PATH environment variables (tutorial)
  5. Restart your terminal / code editor

You should now be able to run sz or sharezone in your terminal.

Clone this repository

Before you can clone this repository, you need to install git. After installing git, run this command:

git clone https://github.com/SharezoneApp/sharezone-app.git

After cloning the repository, we recommend executing the following steps:

  1. Get all dependencies with fvm flutter pub get

Flutter Version Management (FVM)

We use FVM to have a consistent Flutter version across the developers and our CI/CD. You find in .fvmrc the Flutter, which we currently using.

To install & use FVM, follow the following steps:

  1. Install FVM by running dart pub global activate fvm or using the other installation methods (see FVM docs)
  2. Navigate to the root of the repository
  3. Run fvm install (This installs the Flutter version from .fvmrc)

When you are using VS Code, no further steps should be necessary. However, when you are using Android Studio, you need to configure your IDE to use the Flutter version of FVM. Follow the official documentation to configure Android Studio.

FlutterFire CLI

If you want to use build the macOS app, you need to install the FlutterFire CLI. This CLI is used during the build process.

To install the FlutterFire CLI, execute the following command:

fvm flutter pub global activate flutterfire_cli 1.3.1

Make sure, you have the 0.3.0-dev.19 version or higher installed. You can check the version by running flutterfire --version.

Running the app

After you have set up your development environment, you can run the app.

First change the working directory to the app folder by running:

cd app

To run the app, you can then execute the following command:

Android, iOS & macOS

fvm flutter run --flavor dev --target lib/main_dev.dart

Web

fvm flutter run --target lib/main_dev.dart

This command runs the app in the development mode. Keep in mind that the app will not use our production backend. Instead, it will use the development backend. This means that you can't use the app with your production account. You need to create a new account on the development backend.

Tests

We use several types of tests to ensure the quality and stability of Sharezone:

  • Unit Tests: Verify the logic of individual functions or classes in isolation.
  • Widget Tests: Test widgets’ UI and interaction behavior without running the full app.
  • Golden Tests: Compare rendered widgets to “golden” reference images to detect unintended visual changes.
  • Integration Tests: Run the app on a device or emulator to test end-to-end flows.

Executing all tests

You execute all tests (except integration tests) with the following command:

sz test

Note

This command is relatively slow because it runs all tests across all packages. During development, you may want to only run a subset of tests to speed things up.

Executing unit & widget tests

To run all unit and widget tests, use:

sz test --exclude-goldens

You can also run tests for a specific directory or file:

# Run all unit & widget tests in the app directory
fvm flutter test app/test/

# Run only tests for the "grades" feature
fvm flutter test app/test/grades

# Run a single test file
fvm flutter test app/test/grades/grades_service_test.dart

Executing golden tests

To run only golden tests, execute:

sz test --only-goldens

You can also limit golden tests to specific directories or files:

# Run all golden tests for the app
fvm flutter test app/test_goldens/

# Run golden tests for the "grades" feature
fvm flutter test app/test_goldens/grades

# Run a single golden test file
fvm flutter test app/test_goldens/grades/pages/grades_page/grades_page_test.dart

Warning

Golden tests currently only pass on macOS due to rendering differences across platforms. See Known Issues for details.

To generate (or update) golden files, use:

# Generate golden files for all tests:
sz test --update-goldens

# Generate golden files for a directory, e.g. "grades"
fvm flutter test app/test_goldens/grades --update-goldens

# Generate golden files for a single file, e.g. grade_page_test.dart
fvm flutter test app/test_goldens/grades/pages/grades_page/grades_page_test.dart --update-goldens

Executing integration tests

Please see app/integration_test/README.md for detailed instructions on how to run integration tests.

Internationalization (i18n / l10n)

We organize our multi-language support in the lib/sharezone_localizations package.

Adding new strings

  1. Add the new string to lib/sharezone_localizations/l10n/app_de.arb. This is our default language.
  2. Add the new string to lib/sharezone_localizations/l10n/app_en.arb. Metadata (e.g. @your_new_string) should only be added to the German file.
  3. Run sz l10n generate to generate the Dart files for the new string.

Use new strings

  1. Add import 'package:sharezone_localizations/sharezone_localizations.dart'; to the file where you want to use the new string.
  2. Use the new string like this: context.l10n.your_new_string.