First of all, a word of welcoming to whomever has landed on this page. If you are here, that means that somehow you have found a link to this project over the Internet, you are possibly interested in it (either positively or negatively) and you are wondering whether you can contribute in any way.
This is great news, so thank you for your time and dedication. Whether you spend 1 minute or 1 hour here, it is really highly appreciated.
With no further ado, here is a short list of what you'll find here. Keep in mind that, like the project in under continuous development and evolution (hopefully), so is this guide. New sections will be added and new answers will be provided as long as questions are submitted.
- section 1 will provide a general overview about the project and its contributors: who we are, what we are trying to achieve, why are we doing it and how;
- section 2 illustrates the core values that are behind this project, its key goals and an acknowledgement to all the people who helped us to achieve those targets;
- section 3 is a collection of operative instructions for those who want to contribute, either reporting bugs, asking for new features, submitting feedback, contributing with code, documentation or translations;
- section 4 is dedicated to developers wanting to build the project locally in order to submit pull requests;
- section 5 contains a technical illustration of the tech stack used in the project how the project is broken down into discrete components that interact with each other;
- section 6 contains the architectural patterns used in the project and the coding conventions you should follow when submitting PRs, because readability and consistency matter and there are some rules (with exceptions) that should ideally be followed everywhere.
Raccoon was designed with three goals in mind: on the one side experiment and put to some stress
test with a real world project Kotlin Multiplatform (KMP) and Compose multiplatform, in order
to explore what could be achieved with multiplatform libraries and share as much code as possible
in the commonMain source directory. The Android ecosystem of Lemmy apps has many cross-platform
alternatives implemented with Flutter or React, a couple of native options written in Java and just
one native pure-Kotlin application. Raccoon intends to be an Android-first app, but
experimentation on other OSes given the multiplatform nature of its technologies are not
excluded a priori.
The second goal was to offer a feature rich Lemmy client mainly aimed at "pro" users, i.e. users who are not content with just browsing the contents of the Fediverse, creating posts and answers. This is why Raccoon tried to offer from the very beginning features like:
- a full-fledged explore section that allows multiple result types
- instance info, with the list of communities of foreign instances as well as the possibility to visit communities on foreign instances in guest mode
- multi-community, i.e. community aggregation
- moderation tools (for community moderators) and access to community moderation log.
Finally, the third goal was to offer a Lemmy experience where everyone could "feel at home" (see the Code of Conduct below). This implies keeping the interface lean by default but having the possibility to customize a variety of aspects (theme, vote format, default feed/sort type) and adopt the user's native language. As a consequence, leanness, personalization and localization are first-class citizens in this project.
Lemmy users used to refer to themselves as "lemmings" and the platform logo clearly recalls that animal, so there was this tradition in the early days to use animals names for clients -- or at least the original developers of this app thought so (some examples being Lemmur, Jerboa and Fennec). Since they really liked raccoons, they choose that: raccoons are cunning animals that adapt to live in harsh conditions, finding a way to survive even with what we consider "trash". They look like masked criminals but do not harm anyone, they are lazy, chubby and absolutely cute.
In this group, we often quote every raccoon's motto: «Live Fast, Eat Trash» (abbreviated L.F.E.T.).
This section is probably going to change over time, anyway we are a small group of volunteers who in their spare time contribute to the project.
When interacting with other members of the community, be them end-users, developers, supporters or whatever, remember that we are raccoons, and we follow these principles:
| Principle | Explanation | |
|---|---|---|
| R | Respect | We respect each other as people, remembering we are part of a group that goes beyond individual opinions, beliefs, preferences and habits. |
| A | Availability | We support each other with the skills and available time that we have, considering that we are volunteers and we operate on a best-effort basis. |
| C | Commitment | We are responsible for our choices and we agree that our choices are taken wisely, always considering the impact on other members of the group. |
| C | Cohesion | We remember that we are part of a community which is bigger than the individual members, so we do unto others as we would have them do unto us. |
| O | Objectivity | We are committed to telling the truth in the most objective way and, if we express subjective opinions, to do it in a clear and constructive way. |
| O | Originality | We bring our own personal experience and ideas which are acceptable even if "different": everyone's voice matters and deserves to be listened. |
| N | Never give up | We are tenacious and are not afraid by technical challenges, we embrace every difficult task as an opportunity to learn and acquire new skills. |
There are many ways you can interact with members of the community:
- use the Lemmy community to receive updates about the new releases, participate into public discussions in the Lemmy style and provide your feedback or even share your memes about raccoons with any other interested people;
- use the GitHub issue tracker to report bugs or request features;
- use the GitHub discussion section for technical questions about the release roadmap, questions about app internationalization, etc.;
- finally, if none of the above methods fits your needs you can write an email or send a private message to the original developer (my personal information are in the GitHub profile).
Always remember the guidelines contained here and here to interact with other people: our values are important and should be applied even with each other and not only with end users.
The preferred way to submit a bug report is the GitHub issue tracker.
- use the "New issue" button to open the creation form
- in the "Add a title" field give a synthetic description of the issue, if it affects a specific
part of the application you can add in square brackets a prefix containing that information,
e.g.
[post list]orpost detailor[create report]. - in the "Add a description" field provide a more detailed explanation of the issue, you can use
Markdown syntax (in the GitHub flavour) to format text here.
An ideal bug report contains:
- the precondition (sequence of steps that lead to the faulty condition, if it is deterministic)
- a description of the error condition (with the expected result and the actual result, where the difference between the two is clear)
- (if you can, optionally) some screenshots that make it clear where the error is
- you can add the "bug" label to the issue or otherwise leave it blank. Do not use the other fields (assignee, milestone, etc.) because they are used internally by the team members who will take the issue in charge during resolution.
As for bug reports, the preferred way for feature or change requests is the GitHub issue tracker. In this case, you should:
- insert a short description in the title field, if the feature is specific to some app domain you can use the same square bracket prefix as in bug reports
- insert a more detailed explanation of your idea in the description field, if your feature is present in other apps you can provide screenshots or make references to make the request clearer
- you can use the "feature" label to tag the issue, or otherwise leave it blank and let the maintainers decide how to triage the issue.
Note
This section explains how translation are managed in the app (creating a new implementation of the Strings interface, modify the bottom sheet to allow selecting it etc.) and it is useful to understand the global mechanism. However, translators are encouraged to review the messages on Weblate and leave all the heavy-lifting work to project maintainers.
The project uses the Lyricist library for internationalization, which relies on Composition Locals to access strings in Composables.
In order to add a new language, you will have to create a new implementation of the Strings
interface inside the :core:l10n module, namely under the messages package in the commonMain
source set.
First of all, determine the locale code, suppose it is xx_YY, based on the IANA conventions: it
can
consist a set of letters for the language xx, optionally followed by an underscore and another
letter
set for the region YY (e.g. pt_BR for Brazilian Portuguese or pt for Portuguese). If you only
have to use the xx part, please ignore the yy indication in the rest of the explanation
contained in this paragraph.
Inside the messages package, create a file named XxYyStrings.kt which will contain an
anonymous implementation of Strings stored in a variable called XxYyStrings like this
internal val XxYyStrings =
object : Strings {
override val actionBackToTop = "..."
// ... continue overriding all the remaining properties
}It is recommended to copy the contents of the existing EnStrings.kt (i.e. the base localization)
in order to already have all the overridden properties and just rewrite the values in quotes.
While editing messages, please escape all apostrophes (') with a backslash (\'); while not
strictly needed any more, it's for compatibility with the old XML format used for localization.
Afterwards, edit the Strings.kt file in the same directory with the following modifications:
object Locales {
// ...
const val XX_YY = "xx_YY"
}
internal val localizableStrings: Map<LanguageTag, Strings> =
mapOf(
// ...
Locales.XX_YY to XxYyStrings,
)Finally, if you want you can change the rest of the code (e.g. the language dialog, etc) please do the following:
- in Extensions.kt add your flag and language name (mapping your language code to the values)
- add an option (using your language code) in the
valuesarray in LanguageBottomSheet.kt
That's it! You can test that everything works by launching the development app.
A note for translators: the strings that correspond to theme names (settingsColorAquamarine,
settingsColorBanana, settingsColorBlue, settingsColorGray, settingsColorGreen,
settingsColorOrange, settingsColorPink, settingsColorPurple, settingsColorRed and
settingsColorWhite) contain the name of an animal accompanied by an adjective. It would be nice
if the adjective and the noun would start in every language with the same sound in order to create
humorous pairs like in English ("hilarious hedgehog", "frolicsome frog", etc.).
However, if you are not a developer and do not feel confident with GitHub's PR mechanism, you can just download the base l10n to your local machine, edit the file and send an email to the maintainers with the attachment, we will take care of the rest.
If you have proposals, want to submit l10n fixes/improvements to existing ones, you can use this discussion and post an answer, we will reach out to you and solve the issue.
First of all, please fork the repository by using the "Create a new fork" button in the GitHub console, which will create a copy of the repository in your personal account.
Create a branch from the repository's master branch named after the feature/change you want to submit, use whatever convention you like (preferably underscores to separate words but as you wish) and make any commits you want on it.
Push the commits on the remote branch of your forked repository.
Use the "Compare and pull request" button to see a recap of the PR, after which use the "Create pull request" to submit the request to the upstream repository.
This project uses the Gradle build tool. The recommended development environment is Android Studio with the Kotlin Multiplatform Mobile plugin installed, which will automatically detect the build tool and download a Gradle distribution for you.
Since the project is using Gradle 8.8 with the Android Gradle Plugin (AGP) version 8.5.0 please make sure that you are using Android Studio Koala or later -- have a look here for a compatibility matrix between versions of Gradle, AGP and Android Studio.
In order for Gradle to build, you will need a JDK installed on your local development machine, if you are using stock Android Studio it ships with the JetBrains runtime. If you want to use your custom JDK (e.g. under Linux you want to try OpenJDK instead), please make sure that it has a suitable version, according to this page.
Finally, since building this project requires quite a lot of RAM, please make sure that
the gradle.properties file in the root folder contains proper memory settings for the JVM and the
Kotlin compile daemon:
org.gradle.jvmargs=-Xmx4096M -Dfile.encoding=UTF-8 -Dkotlin.daemon.jvm.options\="-Xmx4096M"The project is organized as a multi-module Gradle projects, meaning that it is split into a series of interdependent Gradle subprojects and that there is a module hierarchy in which multiple levels.
The modules can be grouped into five groups:
- top-level and special modules: these modules are tied to the project setup and contain the entry point of the app (include everything);
- feature modules: these that correspond to the main functions of the application, i.e. the five tabs that can be found in the tab bar that live independently and made up the basic structure. Feature modules can be included by top-level modules but can not include each other. They can include domain modules, unit modules or core modules.
- domain modules: a series of purely business logic modules containing code related to specific domains such as user identity management, all the Lemmy specific business logic (APIs and inbox). Domain modules can only include core modules and can be included by feature modules, unit modules or top-level ones.
- unit modules: reusable parts of the application containing UI components and a thin layer of presentation logic that are used to render the various screens, bottom sheets and dialogs of the application, grouped by feature so that each block can be called from multiple points. Unit modules are used by feature modules and can include domain modules, core modules or in some limited cases other unit modules (but never cyclically!).
- core modules are the foundational layer of the application. They are included by unit modules,
feature modules, domain modules and top-level modules. They should not include anything except in
some rare occasions, other core modules (but never cyclically!). A notable example of this is the
:core:markdownmodule (Markdown rendering) that includes:core:commonui:componentsbecause Markdown requires some custom UI components to be rendered.
For more detailed information about the contents of each group and the purpose of each module, please refer to this page.
The project’s architecture is inspired from the Clean architecture principles. Modules are organized in tiers and dependency flows goes from higher modules (top-level and feature modules) towards lower order modules (unit modules for UI, domain modules for business logic) which in turn rely on core modules for low-level operations; and that is a hierarchical structure on the vertical axis. Apart from that, there is a split on the horizontal axis (i.e. different features for different sections of the app). The intersection between these two axes determines the modularization strategy.
To summarize, if you are looking for something related to the app UI, have a look at :feature:xxx
or :unit:xxx (and possibly you will have to drill down to :core:commonui:xxx). If you are
searching for some piece of interaction with Lemmy APIs, have a look at :domain:lemmy:xxx (and
you’ll probably end up in :core:api for more low-level minutia), if you look for data access on
the local database have a look at :core:persistence, and so on. More on this here (Modularization
strategy).
Every part of the app which has some non trivial user-interaction follows the Model-View-Intent architectural pattern. This means that there are two different components interacting with each other:
- the View, represented by a
Screenimplementation - the ViewModel, represented by a
ScreenModelimplementation
where the interfaces (Screen and ScreenModel) both come from the Voyager navigation library.
The View has the responsibility of drawing to screen the UI components that are needed to represent a particular state, which is provided by the ViewModel they have a reference to (the ViewModel being a state holder for this respect). The View has also the ability to collect user input (or, rather, intentions as intents) and dispatch them to the ViewModel.
On its side, the ViewModel holds an observable state and has the ability to react to user intents coming from the View, each of which implies some business logic operations which, in turn, determine ultimately a state change, observed by the view. In some less frequent case, the ViewModel can emit one-time events, that are unrelated to persistent state and can determine volatile effects in the View.
These concepts of a ViewModel having to deal with Intent, State and Effect are modelled in Kotlin in
the :core:architecture module which is included as a building block by all UI related features and
unit modules of the project. The MviModel interface defined here is a common supertype of all the
ScreenModel implementations.
In case some event needs to be propagated across different ViewModels, the event bus defined
in :core:notifications is used.
Please refer to this page for the conventions to apply to Kotlin code.
As far as Compose code is concerned, we take Google’s indications as a baseline:
The recommended lint to use is Ktlint with
the ktlint_official code
style. There is a plugin for IntelliJ/Android Studio that allows to have distraction-free formatting
upon saving, to
make sure any new code is compliant with the rules.
Unit test are targeted as a single unit of code: the test class will have the same name of the
component under test, followed by the Test suffix and will be placed in the same package, within
the androidUnitTest source set. The tests will be platform specific for now, since multi-platform
tests under the commonTest set require some additional setup and a considerable amount of extra
effort.
For every subject under test (SUT), the dependencies will be doubled using test mocks created using
the mockk library, and the assertions on flows and channels will be made using the turbine
library.
Each test class will contain at least one method annotated with @Test and, especially if it
contains suspending functions, its body will be wrapped in a runTest scope function (better to
always include it). In order for suspending functions to be called in the correct coroutine
context (where the main thread of Android is replaced by an Unconfined dispatcher), the JUnit rule
DispatcherTestRule defined in :core:testutils should be included and annotated with @get:Rule.
Each test method shall consider a single interaction (W) on the SUT that happens in a precondition (G) and should produce a result (T) against which some assertions will be performed.
These three elements will be reflected in the method name, which shall have the GWT form, i.e.:
givenX_whenY_thenZ
The body of the method will be therefore divided into three parts (separated by a blank line):
- (optional) precondition: mock setup with predefined answers to invocations;
- interaction: the method/property to test will be invoked/interacted with on the SUT;
- result: one or more assertions on the result got in the previous step; optionally this part will also contains some verification on the mocks/spies to make sure the proper interactions have or have not happened according to the expectations in the previous step.
Reference unit test:
class DefaultNavigationCoordinatorTest {
// coroutine test rule (must be a public property)
@get:Rule
val dispatcherRule = DispatcherTestRule()
// subject under test
private val sut = DefaultNavigationCoordinator()
// test method (1)
@Test
fun givenNavigatorCanPop_whenRootNavigatorSet_thenCanPopIsUpdated() = runTest {
// setup
val navigator = mockk<Navigator> {
every { canPop } returns true
}
// interaction
sut.setRootNavigator(navigator)
// assertions
val value = sut.canPop.value
assertTrue(value)
}
// test method (2)
@Test
fun whenChangeTab_thenCurrentTabIsUpdated() = runTest {
// setup with capturing slots
val tabSlot = slot<Tab>()
val navigator = mockk<TabNavigator>(relaxUnitFun = true) {
every { current = capture(tabSlot) } answers {}
}
val tab = object : Tab {
override val options @Composable get() = TabOptions(index = 0u, "title")
@Composable
override fun Content() {
Box(modifier = Modifier.fillMaxSize())
}
}
sut.setTabNavigator(navigator)
// interaction
sut.changeTab(tab)
// assertions
val value = tabSlot.captured
assertEquals(tab, value)
}
// test method (3)
@Test
fun whenSubmitDeeplink_thenValueIsEmitted() = runTest {
val url = "deeplink-url"
// interaction
sut.submitDeeplink(url)
// assertions on the flow with turbine's test extensions
sut.deepLinkUrl.test {
val value = awaitItem()
assertEquals(url, value)
}
}
}