Skip to content

Latest commit

 

History

History
124 lines (86 loc) · 4.11 KB

CONTRIBUTING.md

File metadata and controls

124 lines (86 loc) · 4.11 KB
Raw

Contributing

Looking to contribute to Aegis? That's great! There are a couple of ways to help out. This document contains some general guidelines for each type of contribution.

Please review the FAQ before reporting a bug, asking a question or requesting a feature.

Translations

We use Crowdin to crowdsource translations of Aegis for lots of different languages. Pull requests that add/update a translation are no longer accepted. Crowdin is our single source of truth for translations, to keep things easy to maintain.

The top 30 languages are available for translation. It's possible that yours is not in that list. If that's the case, feel free to send us an email and we'll add it.

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. To make bug reports easier to follow up on for us, please fill out the form as accurately as possible. If a bug report does not contain enough information, it will be closed. Duplicate bug reports receive the same treatment.

Please consider trying to find the root cause yourself first and include your analysis of the issue in your report. Perhaps even send us a patch that fixes it! 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 > 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) > 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.