Fabio/Auxio
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: rework contribution info

Browse source 
Update the contribution information and templates.

The contribution information and templates were growing a bit stale,
given that they haven't gotten a refresh since ~1.3.0. This commit
reworks them to be more thorough and straightfoward.
This commit is contained in:
OxygenCobalt 2022-02-06 14:30:07 -07:00
parent 470187422a
commit d9e2d7f07a
No known key found for this signature in database
GPG key ID: 37DBE3621FE9AD47
10 changed files with 42 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
.github/CONTRIBUTING.md vendored
View file

@ -1,7 +1,6 @@
# Auxio contribution guidelines
## Crashes & Bugs
Log them in the [Issues](https://github.com/OxygenCobalt/Auxio/issues) tab.
Please keep in mind when reporting an issue:
@ -17,7 +16,6 @@ If you do make an issue, Make sure to provide:
If you have knowledge of Android/Kotlin in general, you could also go about fixing the bug yourself and opening a [Pull Request](https://github.com/OxygenCobalt/Auxio/pulls).
## Feature Requests
These should also be logged in the [Issues](https://github.com/OxygenCobalt/Auxio/issues) tab.
Please keep in mind when requesting a feature:
@ -34,17 +32,14 @@ If you have the knowledge, you can also implement the feature yourself and creat
Its also recommended that you read about [Auxio's Architecture](../info/ARCHITECTURE.md) as well to make changes better and more efficient.
## Translations
I still need to setup weblate, so currently you should open a [Pull Request](https://github.com/OxygenCobalt/Auxio/pulls) to add translations to the strings.xml for your specific language.
I don't really see the use in weblate, so currently you should see the [Translations Megathread]](https://github.com/OxygenCobalt/Auxio/issues/3) to see how to propose translations.
## Code Contributions
If you have knowledge of Android/Kotlin, feel free to to contribute to the project.
- If you want to help out with an existing bug report, comment on the issue that you want to fix saying that you are going to try your hand at it.
- If you want to add something, its recommended to open up an issue for what you want to change before you start working on it. That way I can determine if the addition will be merged in the first place, and generally gives a heads-up overall.
- Do not bring non-free software into the project, such as Binary Blobs.
- Stick to [F-Droid Contribution Guidelines](https://f-droid.org/wiki/page/Inclusion_Policy)
- Stick to [F-Droid Including Guidelines](https://f-droid.org/wiki/page/Inclusion_Policy)
- Make sure you stick to Auxio's styling with [ktlint](https://github.com/pinterest/ktlint). `ktlintformat` should run on every build.
- Please ***FULLY TEST*** your changes before creating a PR. Untested code will not be merged.
- Java code will **NOT** be accepted. Kotlin only.

21
.github/ISSUE_TEMPLATE/bug-crash-report.md vendored
View file

@ -10,6 +10,9 @@ assignees: ''
#### Describe the bug/crash:
<!-- A clear and concise description of what the bug or crash is. -->
#### Expected behavior
<!-- Include behavior of other android music players, if applicable. -->
#### Steps To Reproduce the bug/crash:
<!--
1. Go to X
@ -19,14 +22,26 @@ assignees: ''
-->
#### Logs/Stack Traces:
<!-- If possible, provide a stack trace or a Logcat. This can help identify the issue. -->
<!--
If possible, provide a stack trace or a Logcat. This can help identify the issue.
To take a logcat, you must do the following:
1. Use a desktop/laptop to download the android platform tools from https://developer.android.com/studio/releases/platform-tools.
2. Extract the downloaded file to a folder
3. Enable USB debugging on your phone [See https://developer.android.com/studio/command-line/adb#Enabling], and then connect your
phone to a laptop. You will get a prompt to "Allow USB debugging" when you run the logcat command. Accept this.
4. Open up a terminal/command prompt in that folder and run:
- `./adb -d logcat | grep -i "[DWE] Auxio"` in the case of a bug [may require some changes on windows]
- `./adb -d logcat AndroidRuntime:E *:S` in the case of a crash.
5. Copy and paste the output to this area of the issue.
-->
#### Screenshots:
<!-- If applicable, add screenshots to help explain your problem. -->
#### Phone Information:
<!-- Please provide information about your phone's android version/model. -->
<!-- Please provide information about your phone's manufacturer, model, android version, and skin. -->
#### Due Diligence:
- [ ] I have checked this issue for any duplicates.
- [ ] I have checked for this issue in the [FAQ](https://github.com/OxygenCobalt/Auxio/blob/dev/info/FAQ.md).
- [ ] I have read the [Contribution Guidelines](https://github.com/OxygenCobalt/Auxio/blob/dev/.github/CONTRIBUTING.md).

12
.github/ISSUE_TEMPLATE/feature-request.md vendored
View file

@ -11,11 +11,15 @@ assignees: ''
<!-- A clear and concise description of what you want to be added. -->
#### Is your feature request related to a problem? Please describe:
<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when... -->
#### Do other music players handle this? If so, how?
<!-- This is optional, but recommended. -->
#### Why do you think this will improve everyone's usage of Auxio?
<!-- Provide a rationale here -->
<!-- Providing a good argument may convince me to approve this feature. -->
#### Due Diligence:
- [ ] I have read [Accepted Additions and Requests](https://github.com/OxygenCobalt/Auxio/blob/dev/info/ADDITIONS.md) and the [Contribution Guidelines](https://github.com/OxygenCobalt/Auxio/blob/dev/.github/CONTRIBUTING.md).
- [ ] I have read the [Contribution Guidelines](https://github.com/OxygenCobalt/Auxio/blob/dev/.github/CONTRIBUTING.md).
- [ ] I have read the [Accepted Additions and Requests](https://github.com/OxygenCobalt/Auxio/blob/dev/info/ADDITIONS.md) document.
- [ ] I have checked for this feature in the [FAQ](https://github.com/OxygenCobalt/Auxio/blob/dev/info/FAQ.md).

20
.github/PULL_REQUEST_TEMPLATE.md vendored
View file

@ -1,28 +1,28 @@
<!-- Please fill out all this information. -->
**What is it?**
#### What is it?
- [ ] Bugfix (user facing)
- [ ] Feature (user facing)
- [ ] Translation to: <!-- Include the language here. Note if this translation is for a regional dialect. --> (user facing)
- [ ] Codebase improvement (dev facing)
- [ ] Meta improvement to the project (dev facing)
**Description of changes**
#### Description of changes
<!-- Bullet points or free-form text -->
- Do this
- Fix that
- Listen to music
**Fixes the following issues**
#### Fixes the following issues
<!-- Also add any other links relevant to your change. -->
-
**Any additional information**
#### Any additional information
<!-- Also add any information relevant to this PR. -->
**APK testing**
<!-- Please create a debug APK for your changes. -->
#### APK testing
<!-- Please create a debug APK for your changes, if possible. -->
debug.zip
**Due Diligence**
- [ ] I have read the [Contribution Guidelines](https://github.com/OxygenCobalt/Auxio/blob/dev/.github/CONTRIBUTING.md) and [Accepted additions & Requests](https://github.com/OxygenCobalt/Auxio/blob/dev/info/ADDITIONS.md).
#### Due Diligence
- [ ] I have read the [Contribution Guidelines](https://github.com/OxygenCobalt/Auxio/blob/dev/.github/CONTRIBUTING.md).
- [ ] I have read the [Accepted additions & Requests](https://github.com/OxygenCobalt/Auxio/blob/dev/info/ADDITIONS.md) document.

1
CHANGELOG.md
View file

@ -20,6 +20,7 @@ artist they are grouped up in
#### Dev/Meta:
- Removed 1.4.X compat
- Added new changelog document
## v2.1.0
#### What's New:

2
app/src/main/java/org/oxycblt/auxio/playback/system/AudioReactor.kt
View file

@ -98,8 +98,6 @@ class AudioReactor(
return
}
logD("$metadata")
// ReplayGain is configurable, so determine what to do based off of the mode.
val useAlbumGain: (Gain) -> Boolean = when (settingsManager.replayGainMode) {
ReplayGainMode.OFF -> {

6
info/ADDITIONS.md
View file

@ -1,17 +1,13 @@
# Accepted Additions and Requests
One of the reasons I built Auxio was out of frustration with other FOSS android music players, which had too many features, frustrating UI/UX flaws, or both. Therefore any additions will have to be accepted by **me** (OxygenCobalt) before they are implemented or merged.
## Bug Fixes, Optimizations, Architecture Improvements, etc.
These will likely be accepted as long as they do not cause too much harm to the codebase.
## New Customizations/Options
While I do like adding new behavior/UI customizations, these will be looked at more closely as certain additions can cause harm to the apps UI/UX while not providing alot of benefit. These tend to be accepted however.
## Feature Addtions and UI Changes
These arent as likely to be accepted. As I said, I do not want Auxio to become overly bloated with features that are rarely used, therefore I only tend to accept features that:
- Benefit **my own** usage
@ -22,12 +18,10 @@ This does not rule out these additions, but they are not accepted as often as ot
Feel free to fork Auxio to add your own feature set however.
#### Additions that have already been rejected (and why):
- Folder View/Grouping [#10] (Out of scope)
- Recently added list [#18] (Out of scope)
- Lyrics [#19] (Out of scope)
- Tag editing [#33] (Out of scope)
- Gapless Playback [#35] (Technical issues)
- Reduce leading instrument [#45] (Technical issues, Out of scope)
- Disabling track numbers [#73] (Out of scope)
- Opening music through a provider [#30] (Out of scope)

22
info/ARCHITECTURE.md
View file

@ -1,13 +1,10 @@
# Architecture
This document is designed to provide an overview of Auxio's architecture and design decisions. It will be updated as Auxio changes.
## Core Facets
Auxio has a couple of core systems or concepts that should be understood when working with the codebase.
#### Package Structure
Auxio's package structure is strictly feature-oriented. For example, playback code is exclusively in the `playback` package,
and detail code is exclusively in the `detail` package. Sub-packages can be related to the code it contains, such as `detail.recycler`
for the detail UI adapters, or they can be related to a sub-feature, like `playback.queue` for the queue UI.
@ -41,7 +38,6 @@ org.oxycblt.auxio # Main UIs
Each package is gone over in more detail later on.
#### UI Structure
Auxio only has one activity, `MainActivity`. Do not try to add more activities to the codebase. Instead, a new UI
should be added as a new `Fragment` implementation and added to one of the two navigation graphs:
@ -74,7 +70,6 @@ the attributes directly unless absolutely necessary. Usually it's okay to apply
to duplicate layouts simply because they apply to different data objects, such as the detail UIs.
#### Object communication
Auxio's codebase is mostly centered around 4 different types of code that communicates with each-other.
- UIs: Fragments, RecyclerView items, and Activities are part of this class. All of them should have little data logic
@ -91,7 +86,6 @@ Ideally, UIs should only be talking to ViewModels, ViewModels should only be tal
should only be talking to other shared objects. All objects can use the utility functions where appropriate.
#### Data objects
Auxio represents data in multiple ways.
`BaseModel` is the base class for most music and UI data in Auxio, with a single ID field meant to mark it as unique.
@ -117,7 +111,6 @@ poor UX to the user.
- For `Album` instances in particular, prefer `resolvedArtistName` over `artist.resolvedName`
#### Music Access
All music on a system is asynchronously loaded into the shared object `MusicStore`. Because of this, **`MusicStore` may not be available at all times**.
- ViewModels should try to await or gracefully exit the called method if `MusicStore` is not available
@ -127,7 +120,6 @@ All music on a system is asynchronously loaded into the shared object `MusicStor
If the loading status needs to be shown in a UI, `MusicViewModel` can be used to observe the current music loader response.
#### Playback System
Auxio's playback system is somewhat unorthodox, as it avoids much of the android-provided APIs in favor of a more controllable and sensible system.
The diagram below highlights the overall structure and connections:
@ -158,7 +150,6 @@ system events, such as when a button is pressed on a headset. It should **never*
`PlaybackViewModel` exposes the same data in a much safer fashion.
#### Data Integers
Integer representations of data/UI elements are used heavily in Auxio, primarily for efficiency.
To prevent any strange bugs, all integer representations must be unique. A table of all current integers used are shown below:
@ -219,19 +210,16 @@ the documentation for those datatypes.
## Package-by-package rundown
#### `org.oxycblt.auxio`
This is the root package and contains the application instance and the landing UIs. This should be kept sparse with most other code being placed
into a package.
#### `.accent`
This package is responsible for Auxio's color schemes, internally known as accents due to legacy code.
It contains an object that represents the attributes of an accent, but this should be avoided in favor of
resolving color attributes directly, such as `colorPrimary`. This package also contains the UIs for picking
an accent.
#### `.coil`
[Coil](https://github.com/coil-kt/coil) is the image loader used by Auxio. All image loading is done through these four functions/binding adapters:
- `app:albumArt`: Binding Adapter that will load the cover art for a song or album
@ -245,7 +233,6 @@ Internally, multiple fetchers are provided to transform `Music` instances into i
the necessary methods for loading album artwork and creating the mosaics shown in artist/genre images.
#### `.detail`
Contains all the detail UIs for some data types in Auxio. All detail user interfaces share the same base layout (A Single RecyclerView) and
only change the adapter/data being used. The adapters display both the header with information and the child items of the item itself, usually
with a data list similar to this:
@ -258,7 +245,6 @@ Each adapter instance also handles the highlighting of the currently playing ite
navigation [Such as when a user presses "Go to artist"]
#### `.excluded`
This package is responsible for the excluded directory system. It contains the database of excluded directories and the dialog that appears when
editing them.
@ -266,7 +252,6 @@ editing them.
compatibility with previous versions of Auxio.
#### `.home`
This package contains the components for the "home" UI in Auxio, or the UI that the user first sees when they open the app.
- The base package contains the top-level components that manage the FloatingActionButton, AppBar, and ViewPager instances.
@ -275,12 +260,10 @@ This package contains the components for the "home" UI in Auxio, or the UI that
- The `tabs` package contains the data representation of an individual library tab and the UIs for editing them.
#### `.music`
This package contains all `BaseModel` implementations and the music loading implementation. This also includes `Header`/`ActionHeader`, as those
data objects have to inherit `BaseModel` so that they can be placed alongside `Music` instances in `RecyclerView` instances.
#### `.playback`
This module not only contains the playback system described above, but also multiple other components:
- `queue` contains the Queue UI and it's fancy item transitions
@ -291,19 +274,16 @@ The most important part of this module is `PlaybackLayout`, which is a custom `V
slide up into the full playback view. `MainFragment` controls this `ViewGroup`.
#### `.search`
Package for Auxio's search functionality, `SearchViewHolder` handles the data results and filtering while `SearchFragment`/`SearchAdapter` handles the
display of the results and user input.
#### `.settings`
The settings system is primarily based off of `SettingsManager`, a wrapper around `SharedPreferences`. This allows settings to be read/written in a
much simpler/safer manner and without a context being needed. The Settings UI is largely contained in `SettingsListFragment`, while the `pref`
sub-package contains `IntListPreference`, which allows Auxio's integer representations to be used with the preference UI. The about dialog
also resides in this package.
#### `.ui`
Shared views and view configuration models. This contains:
- Customized views such as `EdgeAppBarLayout` and `EdgeRecyclerView`, which add some extra functionality not provided by default
@ -312,11 +292,9 @@ Shared views and view configuration models. This contains:
- `memberBinding` and `MemberBinder`, which allows for ViewBindings to be used as a member variable without memory leaks or nullability issues.
#### `.util`
Shared utilities. This is primarily for QoL when developing Auxio. Documentation is provided on each method.
#### `.widgets`
This package contains Auxio's AppWidget implementation, which deviates from other AppWidget implementations by packing multiple
different layouts into a single widget and then switching between them depending on the widget size.

16
info/FAQ.md
View file

@ -1,42 +1,33 @@
# Auxio - Frequently Asked Questions
This FAQ will be continually updated as new changes and updates are made to Auxio.
#### Where can I download Auxio?
Auxio is available on the [F-Droid](https://f-droid.org/en/packages/org.oxycblt.auxio/) repository.
Auxio is not and will never be on the play store due to it being a proprietary and draconian platform.
#### Why ExoPlayer?
ExoPlayer is far more flexible than the native MediaPlayer API, which allows consistent behavior across devices & OEMs and the
ability to be extended to music sources outside of local files. You can read more about the benefits (and drawbacks) of ExoPlayer
[Here](https://exoplayer.dev/pros-and-cons.html).
#### What formats does Auxio support?
As per the [Supported ExoPlayer Formats](https://exoplayer.dev/supported-formats.html), Auxio supports
MP4, MP3, MKA, OGG, WAV, MPEG, AAC on all versions of Android. Auxio also supports FLAC on all versions
of Android through the use of the ExoPlayer FLAC extension.
#### Auxio doesn't load my music correctly!
This is probably caused by one of two reasons:
1. If other players like Phonograph, Retro Music, or Music Player GO load it correctly, then Auxio has a bug and it should be [reported](https://github.com/OxygenCobalt/Auxio/issues).
2. If the aforementioned players don't work, but players like Vanilla Music and VLC do, then it's a problem with the Media APIs that Auxio relies on. There is nothing I can do about it.
#### I have a large library and Auxio takes really long to load it!
This is expected since reading from the audio database takes awhile, especially with libraries containing 10k songs or more.
#### Auxio does not detect new music!
This is a current limitation with the music loader. To remedy this, go to Settings -> Reload music whenever new songs are added.
I hope to make the app rescan music on the fly eventually.
#### ReplayGain isn't working on my music!
This is for a couple reason:
- Auxio doesn't extract ReplayGain tags for your format.
- Auxio doesn't recognize your ReplayGain tags. This is usually because of a non-standard tag like ID3v2's `RVAD` or
@ -45,25 +36,20 @@ an unrecognized name.
I do plan to add it eventually.
#### What is dynamic ReplayGain?
Dynamic ReplayGain is a quirk setting based off the FooBar2000 plugin that dynamically switches from track gain to album
gain depending on if the current playback is from an album or not.
#### Why are accents lighter/less saturated in dark mode?
As per the [Material Design Guidelines](https://material.io/design/color/dark-theme.html), accents should be less
saturated on dark mode to reduce eye strain and to increase visual cohesion.
#### Does this app keep/send any information about myself or my device?
Auxio does not log any information about the device or its owner, and it has no internet access to send that information off in the first place.
#### How can I contribute/report issues?
Open an [Issue](https://github.com/OxygenCobalt/Auxio/issues) or a [Pull Request](https://github.com/OxygenCobalt/Auxio/pulls),
please note the [Contribution Guidelines](../.github/CONTRIBUTING.md) and [Accepted Additions](ADDITIONS.md) however.
#### Can I translate Auxio to my native language?
See the [Translations](https://github.com/OxygenCobalt/Auxio/issues/3) issue for guidance on how to create translations and submit them to the project.
See the [Translations Megathread](https://github.com/OxygenCobalt/Auxio/issues/3) for guidance on how to create translations and submit them to the project.
Any contributions are appreciated and tend to always be accepted.

1
info/LICENSES.md
View file

@ -1,5 +1,4 @@
# Licenses
Auxio uses a number of third-party libraries, which are listed below with their licenses:
| Library Name | Author(s) | Purpose | License |