From d9e2d7f07a56bdeb78e6213dd4f142cbd059a783 Mon Sep 17 00:00:00 2001 From: OxygenCobalt Date: Sun, 6 Feb 2022 14:30:07 -0700 Subject: [PATCH] docs: rework contribution info 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. --- .github/CONTRIBUTING.md | 11 +++------ .github/ISSUE_TEMPLATE/bug-crash-report.md | 23 +++++++++++++++---- .github/ISSUE_TEMPLATE/feature-request.md | 12 ++++++---- .github/PULL_REQUEST_TEMPLATE.md | 20 ++++++++-------- CHANGELOG.md | 1 + .../auxio/playback/system/AudioReactor.kt | 2 -- info/ADDITIONS.md | 6 ----- info/ARCHITECTURE.md | 22 ------------------ info/FAQ.md | 16 +------------ info/LICENSES.md | 1 - 10 files changed, 42 insertions(+), 72 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 75c2c7895..1f708053e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -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,8 +16,7 @@ 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. +These should also be logged in the [Issues](https://github.com/OxygenCobalt/Auxio/issues) tab. Please keep in mind when requesting a feature: - **Has it already been requested?** Make sure request for this feature is not already here. @@ -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. diff --git a/.github/ISSUE_TEMPLATE/bug-crash-report.md b/.github/ISSUE_TEMPLATE/bug-crash-report.md index 1bc8fbea3..9502d72ff 100644 --- a/.github/ISSUE_TEMPLATE/bug-crash-report.md +++ b/.github/ISSUE_TEMPLATE/bug-crash-report.md @@ -10,6 +10,9 @@ assignees: '' #### Describe the bug/crash: +#### Expected behavior + + #### Steps To Reproduce the bug/crash: #### Logs/Stack Traces: - + #### Screenshots: #### Phone Information: - + #### Due Diligence: - -- [ ] I have read the [Contribution Guidelines](https://github.com/OxygenCobalt/Auxio/blob/dev/.github/CONTRIBUTING.md). +- [ ] 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). \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md index 7a75816ec..463951fd3 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.md +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -11,11 +11,15 @@ assignees: '' #### Is your feature request related to a problem? Please describe: - + + +#### Do other music players handle this? If so, how? + #### Why do you think this will improve everyone's usage of Auxio? - + #### 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). \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a8918d098..1b639fe4b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,28 +1,28 @@ -**What is it?** +#### What is it? - [ ] Bugfix (user facing) - [ ] Feature (user facing) +- [ ] Translation to: (user facing) - [ ] Codebase improvement (dev facing) - [ ] Meta improvement to the project (dev facing) -**Description of changes** +#### Description of changes - Do this - Fix that - Listen to music -**Fixes the following issues** +#### Fixes the following issues -- -**Any additional information** +#### Any additional information -**APK testing** - +#### APK testing + 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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 70e647bf7..df71a38ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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: diff --git a/app/src/main/java/org/oxycblt/auxio/playback/system/AudioReactor.kt b/app/src/main/java/org/oxycblt/auxio/playback/system/AudioReactor.kt index 057ff16ee..ebb31f150 100644 --- a/app/src/main/java/org/oxycblt/auxio/playback/system/AudioReactor.kt +++ b/app/src/main/java/org/oxycblt/auxio/playback/system/AudioReactor.kt @@ -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 -> { diff --git a/info/ADDITIONS.md b/info/ADDITIONS.md index d0a6cdecf..3681bdbcf 100644 --- a/info/ADDITIONS.md +++ b/info/ADDITIONS.md @@ -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) diff --git a/info/ARCHITECTURE.md b/info/ARCHITECTURE.md index a7329803a..9d6a759d3 100644 --- a/info/ARCHITECTURE.md +++ b/info/ARCHITECTURE.md @@ -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. diff --git a/info/FAQ.md b/info/FAQ.md index 16cccec4f..0a209f75c 100644 --- a/info/FAQ.md +++ b/info/FAQ.md @@ -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. diff --git a/info/LICENSES.md b/info/LICENSES.md index 279e124da..568a76005 100644 --- a/info/LICENSES.md +++ b/info/LICENSES.md @@ -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 |