lemmur-app-android/CONTRIBUTING.md

77 lines
4.2 KiB
Markdown
Raw Normal View History

2020-09-22 03:25:50 +02:00
# Contributing
...is welcome!
## Issue tracking / Repository
2022-01-06 15:28:42 +01:00
From issues to wikis: everything is on [GitHub](https://github.com/LemmurOrg/lemmur)
2020-09-22 03:25:50 +02:00
2021-02-19 23:23:23 +01:00
## Linting / Formatting
Everything is formatted with `dart format` (no flags) and linted with `dart analyze` ([see rules](analysis_options.yaml)). Both are enforced by the CI.
2021-02-19 23:23:23 +01:00
## Translations
2022-01-09 21:39:28 +01:00
### Weblate
Lemmy devs are kindly hosting lemmur translation strings on their [Weblate instance](https://weblate.yerbamate.ml/projects/lemmur/lemmur/). Feel free to contribute strings there, we regularly sync string changes with Weblate.
We use flutter's native file format for translations: ARB, which itself uses the ICU message syntax. In most cases you will be able to deduce the syntax based on the source string. Here are 3 important examples:
1. Placeholders
`Hello there {name}!` - placeholders are put in a pair of braces, it will be later replaced with an appropriate value.
2. Plurals
`You have {amount} new {amount, plural, =0{messages} =1{message} =2{messages} few{messages} many{messages} other{message}}` - plurals are checked against their quantifier and provide 6 possible forms to choose from. In english this example does not make much sense, since we could just provide the `=1{message}` and `other{messages}` case. `other` case always has to be specified, it acts as a fallback.
3. Selects
`I will take a {distance_name, select, close{bus} far{train} veryFar{plane}}.` - selects allow for arbitrary matching against some predefined cases. All cases should be the same as in the source string.
### Time ago strings
Strings such as "_About one hour ago_" or "_~1h_" are localizable. We inherit a set of ready translations from [github.com/andresaraujo/timeago.dart/messages](https://github.com/andresaraujo/timeago.dart/tree/master/timeago/lib/src/messages) and provide our own in [lib/l10n/timeago](./lib/l10n/timeago).
To contribute time ago strings please send a PR containing a class that implements `timeago.LookupMessages`. Place it under [lib/l10n/timeago](./lib/l10n/timeago) with an appropriate name (locale tag) and finally register it in [main_common.dart](./lib/main_common.dart) in the `_setupTimeago` function. Each locale can have a normal (for example "_About one hour ago_") and a short (for example "_~1h_") variant, there are registered separately.
2021-02-19 23:23:23 +01:00
2020-09-22 03:25:50 +02:00
## Architecture
2022-01-06 15:28:42 +01:00
Lemmur is written in Dart using [Flutter](https://flutter.dev/docs). To communicate with Lemmy instances [lemmy_api_client](https://github.com/LemmurOrg/lemmy_api_client) is used.
2020-09-22 03:25:50 +02:00
### State management
[`MobX`](https://github.com/mobxjs/mobx.dart) + [Provider](https://github.com/rrousselGit/provider) is used for global state management, [flutter_hooks](https://github.com/rrousselGit/flutter_hooks) is used for local (widget-level) state management. `StatefulWidget`s are avoided all together and any state logic reuse is moved to a [custom hook](./lib/hooks).
2020-09-22 03:25:50 +02:00
### Project structure
(relative to `lib/`)
- `hooks/`: reusable state hooks
2021-02-19 23:23:23 +01:00
- `l10n/`: files with localized strings and localizations tools
2020-09-22 03:25:50 +02:00
- `pages/`: fullscreen pages that you navigate to
2020-10-28 00:00:08 +01:00
- `stores/`: global stores
2020-09-24 01:18:13 +02:00
- `util/`: utilities
2020-09-22 03:25:50 +02:00
- `widgets/`: reusable widgets; building blocks for pages
- `main_common.dart`: entrypoint of the app. Sets up the stores, initializes the themes, renders the first page
2020-09-22 03:25:50 +02:00
### Things to keep in mind
- Be aware that Lemmur supports arbitrary Lemmy instances, don't hardcode instance urls
- Remember that a user is not obligated to be logged in, contributed widgets should handle this case
### Lemmy API
2022-01-06 15:28:42 +01:00
LAC (Lemmy API Client) is used to communicate with Lemmy backends, more information can be found [here](https://github.com/LemmurOrg/lemmy_api_client).
2021-02-19 23:23:23 +01:00
### For React developers
2020-09-22 03:25:50 +02:00
2021-02-19 23:23:23 +01:00
If you come from a React background Flutter shouldn't be anything hard to grasp for you.
- Components are called 'widgets' in flutter
- `flutter_hooks` is a React hooks port to flutter. Though you will come to see that `flutter_hooks` are not as powerful
2022-01-09 21:39:28 +01:00
- There is no CSS. You compose your layout with other widgets and style them by passing properties
- There are no functional components, everything needs to be a class
2021-02-19 23:23:23 +01:00
- Creating wrapping widgets is not as nice as in React, there is no `{ ...props }`. In flutter you need to pass each argument one by one