CONTRIBUTING.md 5.03 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
# Foreword

## Contributing is not only about throwing code

Any project needs several different profiles. Contributing is not only about producing code. 
A good project is a project that has a triving community producing improvement propositions, 
graphic assets, communication, translations, etc.

If you think you are not able to contribute because you cannot produce code: **DON'T**. Please...

Developers are not all-knowing people. They need to colaborate with people having multiple talents. 
Opening a ticket to raise a bug or ask for a feature is already a huge contribution. 
Translating text, propose interface improvement or draw graphics also are.

## If you don't know something, ask

It's ok to not know how to develop an Android application or to use `git`. 
Documentations are good assets if you know what you are searching for and 
how to formulate the question, but sometimes, it's not enough.

In such cases, it's really ok to ask. It's faster and easier and you can be guided. 
Never hesitate to seek help among other contributor. Life is all about learning!

# Technique

26 27
## Setup

28
Before you start developing, you should install [Android studio](https://developer.android.com/studio/install), 
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
Android's, integrated development environment.

This is a fairly standard Android project. There are a few things to know, though, before contributing...

1. This project is a pure Kotlin project. No Java will be tolerated. 
The original author is highly allergic to Java and was very happy to see the Android team embrace Kotlin. 
Since Kotlin is becoming the standard to develop Android applications 
(Android's support library are being rewritten in Kotlin, Jetpack — the Android library for rapid application development — 
is also written in Kotlin, and examples in Android's documentation show Kotlin code by default), this project adopted Kotlin.

2. It also heavily relies on [Jetpack](https://developer.android.com/jetpack/), the Android's rapid application development library. 
In particular, it uses:
    * [JP's data binding](https://developer.android.com/topic/libraries/data-binding/)
    * [`LiveData` classes](https://developer.android.com/topic/libraries/architecture/livedata)
    * [Navigation](https://developer.android.com/topic/libraries/architecture/navigation/)
    * [Room persistence library](https://developer.android.com/topic/libraries/architecture/room) for database interaction,
    * [`ViewModel`s](https://developer.android.com/topic/libraries/architecture/viewmodel)
It would be advised to read [Android's guide to app architecture](https://developer.android.com/jetpack/docs/guide)

3. It uses [Kovenant](http://kovenant.komponents.nl/), as Kotlin promise library to perform async operations.
49

50 51 52 53 54 55 56
4. It uses [Fuel](https://fuel.gitbook.io/documentation/) for HTTP requests.

5. You can debug your application using [Facebook's Stetho](http://facebook.github.io/stetho/).

6. Serialization and deserialization of HTTP request is handled by [Jackson](https://github.com/FasterXML/jackson-core).

## Where to start
57 58 59 60 61 62

Pick [a ticket](https://git.feneas.org/christophehenry/freshrss-android/issues), 
preferably, on that is marked for the next release and start working on it.

Apart from application's features and development, this project is severely 
lacking tests and a good CI pipeline. Feel free to set them up if you feel 
63 64 65 66 67
you have the knowledge.

If you are not a developer, you can contribute by localizing the application in your language. 
Please read the [Android localization guide](https://developer.android.com/guide/topics/resources/localization).

68 69 70 71
## Running tests and linter

Ensure you ran the linters:

Christophe Henry's avatar
Christophe Henry committed
72
```sh
73 74
./gradlew spotlessApply lintFix
```
75

Christophe Henry's avatar
Christophe Henry committed
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
You can automatically configure Android studio to respect the Kotlin lint rules. 
First, download and instal [ktlint](https://ktlint.github.io/) whereever you wish. 
Then, run:

```sh
ktlint --apply-to-idea-project --android
```

You can also add a git hook the will warn you of lint offenses before you commit:

```sh
ktlint --install-git-pre-commit-hook --android
```

To run the Kotlin lint rules alone:

```sh
ktlint -F "app/src/**/*.kt"
```

This will autocorrect what can be autocorrected. Other errors will be printed.

98 99 100 101 102 103 104 105 106 107
# Contributors

## The community and the users

Thank you a lot for using this app, talking about it, loving it ❤️

## Translators

If you want to translate in your language feel free to do so. 
Read [Android's documentation on translations](https://developer.android.com/studio/write/translations-editor).
108 109

* [Fipaddict](https://git.feneas.org/Fipaddict/freshrss-android)
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
  
## UI Graphism

There are no graphists yet. If you think you can improve the look of the application 
please, submit propositions. We desperatly need you.

## UX

* Natouille

## Ticket openers

These section thanks the users opening ticket to raise bug or propose features

* [GLLM](https://git.feneas.org/GLLM)

And others: also thanks to you, anonymous ones that open only one and a fistful of tickets 
on the project. You, too, matter and deserve a thank you.

## Devs

* [Christophe](https://git.feneas.org/christophehenry)