Skip to content

Latest commit

 

History

History
228 lines (166 loc) · 7.9 KB

CONTRIBUTING.md

File metadata and controls

228 lines (166 loc) · 7.9 KB
Raw

Contributing

Every contribution to kubenav is welcome, whether it is reporting a bug, submitting a fix, proposing new features or becoming a maintainer. To make contributing to kubenav as easy as possible you will find more details for the development flow in this documentation.

Please note we have a Code of Conduct, please follow it in all your interactions with the project.

Feedback, Issues and Questions

If you encounter any issue or you have an idea to improve, please:

If you encounter a security vulnerability, please do not open an issue and instead send an email to admin@kubenav.io.

Adding new Features

When contributing a complex change to the kubenav repository, please discuss the change you wish to make within a Github issue with the owners of this repository before making the change.

Development

kubenav uses Flutter and Go, make sure that you have the correct version installed before starting development. You can use the following commands to check your installed version:

$ flutter --version

Flutter 3.24.1 • channel stable • https://github.com/flutter/flutter.git
Framework • revision 5874a72aa4 (12 days ago) • 2024-08-20 16:46:00 -0500
Engine • revision c9b9d5780d
Tools • Dart 3.5.1 • DevTools 2.37.2

$ go version

go version go1.23.0 darwin/arm64

Working with the Go Code

The Go code for kubenav can be found in the cmd folder and we are using the gomobile tools. They can be installed by running the following two commands:

go install golang.org/x/mobile/cmd/gomobile@latest
gomobile init

go get golang.org/x/mobile/cmd/gomobile

To build the code via the gomobile command the ANDROID_HOME and ANDROID_NDK_HOME environment variables must be set. We are using NDK Version 27.0.12077973.

The Android and iOS bindings can then be build using the following Make commands:

  • make bindings-android
  • make bindings-ios

We are using gofmt to format the Go code.

Working with the Flutter Code

In the following section we descibe how to use the Flutter code for the app. When working with the Flutter code ensure that there are no linting errors when you commit your code and that you have sorted all imports.

To sort all imports in the Dart code in a uniformly way you have to run the flutter pub run import_sorter:main command.

Add a Custom Icon

If you have to add a custom icon to the Flutter app we are using https://www.fluttericon.com. The configuration file for all existing icons can be found at utils/images/custom-icons/config.json.

When you add a new custom icon place the .svg file in the utils/images/custom-icons folder. Please also update the config.json file. The content of the generated Dart class should be placed into the lib/utils/custom_icons.dart file.

Add a new Image

To add a new image to the app, place your .svg file in one of the folders in the assets folder. To generate the corresponding .png files the generate.sh script can be used. The script uses Inkscape to generate the .png files from the .svg files in all the required resolutions.

Update Kubernetes Resources

The Kubernetes resources are autogenerated via the swagger.json provided by the Kubernetes project and adjusted afterwards. To generate the all files for the Kubernetes resources the following command can be used:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/kubernetes/kubernetes/v1.25.0/api/openapi-spec/swagger.json \
  -g dart \
  -o /local/out/dart

The swagger file can also be retrieved via the following commands:

kubectl proxy --port=8080
curl localhost:8080/openapi/v2 > swagger.json

Update the Icons and Splash Screen

To update the icon for the app or the splash screens the following two commands can be used:

flutter pub run flutter_launcher_icons:main
flutter pub run flutter_native_splash:create

The icons can be found in the utils/images/app-icons folder. The splash screen icons can be found in the utils/images/splash-screen folder.

Run Debug Build on an Emulator

To list all available emulators the flutter emulators command can be used. Afterwards the emulators can be started as follows:

flutter emulators --launch apple_ios_simulator
flutter emulators --launch Pixel_4_API_30

To run the app on a started emulator the following can be used:

flutter run -d "iPhone 15 Pro Max"
flutter run -d "sdk gphone arm64"

Run Release Build on a Device

To run the release build on a device for testing, we have to get the Device ID first by running the following command:

$ flutter devices

3 connected devices:

Ricos iPad (mobile) • 00008027-0004785E0A31002E • ios            • iOS 16.2 20C65
macOS (desktop)     • macos                     • darwin-arm64   • macOS 13.1 22C65 darwin-arm
Chrome (web)        • chrome                    • web-javascript • Google Chrome 108.0.5359.124

Then we can use one of the listed devices and execute the following command to build and run the app on this device:

flutter run --release --device-id=00008027-0004785E0A31002E

With the above command we can also savely quit the terminal process (by pressing q) and continue testing on the device is not connected to our development machine.

Release

To create a new release for Android and iOS which can be published in Google Play and the App Store the following workflow can be used:

  1. Create a file /android/key.properties with the following content:

    storePassword=
keyPassword=
keyAlias=upload
storeFile=

  2. Update the version key in the pubspec.yaml file

  3. Delete the build/ and .dart_tool/ directories via the flutter clean command.

  4. Run make bindings-android and make bindings-ios to build the Go code for kubenav

  5. Build the app for Android by running flutter build appbundle. The build can be found at /build/app/outputs/bundle/release/app-release.aab and must be uploaded to https://play.google.com/apps/publish

  6. Build the app for iOS by running flutter build ipa. The build can be found at /build/ios/archive/Runner.xcarchive and must be opened in Xcode. In Xcode Validate App and Distribute App can be used to upload the build to https://appstoreconnect.apple.com.