Skip to content

Latest commit

 

History

History
106 lines (73 loc) · 3.4 KB

CONTRIBUTING.md

File metadata and controls

106 lines (73 loc) · 3.4 KB
Raw

Contributing

There are a couple of ways to contribute to Aegis. This document contains some general guidelines for each type of contribution.

Pull requests

If you're planning on adding a new feature or making other large changes, please discuss it with us first through a proposal on GitHub. Discussing your idea with us first ensures that everyone is on the same page before you start working on your change. We don't like rejecting pull requests.

Bug reports

We use GitHub's issue tracker to track bugs. Bug reports must follow the template. If a bug report does not follow the template and does not contain enough information, it will be closed without a response. Duplicate bug reports receive the same treatment.

Please consider trying to find the root cause yourself first and perhaps even send us a patch that fixes the issue! We're happy to help you if you get stuck along the way.

Capturing a log with ADB

In some cases, we ask our users to obtain a debug log from their device. This is typically only necessary if Aegis:

  • Is unable to recover from an error and crashes.
  • Only shows a generic error to the user, but writes a more detailed one to the log.

Capturing a log with the Android Debug Bridge (ADB) allows us to see the stack trace and the exception that occurred.

Preparation

Before you can capture a log, you first need to go through a one-time setup process on your Android device and computer.

Prerequisites
  • Your Android device.
  • A computer with Windows, Mac or Linux.
  • A USB cable to connect your Android device to your computer.
Setup

On your Android device:

  1. Navigate to Settings -> About, scroll down and start tapping on the build number until developer options are enabled.
  2. Navigate to Settings -> System -> Developer options and enable USB debugging.

These navigation steps may differ slightly across Android versions and ROMs.

On your computer:

  1. Download and extract the SDK platform tools for Android: https://developer.android.com/studio/releases/platform-tools.
  2. Start your terminal emulator (If you're on Windows, start PowerShell) and navigate to the folder where platform-tools was extracted.
  3. Execute adb devices.

On your Android device:

  1. A prompt will appear. Select "Always allow from this computer" and accept the connection.

Capturing a log

On your Android device:

  1. Start Aegis.

On your PC:

  1. Start your terminal emulator (If you're on Windows, start PowerShell) and navigate to the folder where platform-tools was extracted.

  2. Start a log capture by executing the following commands.

    adb logcat -c
adb logcat -f debug.log

    The logcat command captures the full system log by default, which may expose some sensitive information. While this information can sometimes help with finding the root cause of the issue, it is not always necessary. To only capture the log output of Aegis, replace the last logcat command with the one below:

    adb logcat --pid=$(adb shell pidof -s com.beemdevelopment.aegis) -f debug.log

    If you are using a debug APK, replace com.beemdevelopment.aegis with com.beemdevelopment.aegis.debug.

On your Android device:

  1. Reproduce the issue.

On your PC:

  1. Stop the log capture with Ctrl+C.
  2. Attach the debug.log file to your issue on GitHub.