mirror/thunderbird-android
0
0
Fork 0
mirror of https://github.com/thunderbird/thunderbird-android.git synced 2024-09-19 19:52:14 +02:00
Code

Change format of Markdown files

Browse Source
This commit is contained in:
Wolf Montwe 2023-02-03 17:28:34 +01:00
parent 71ba065d76
commit 0bf2b31d85
No known key found for this signature in database
GPG Key ID: 24A05D13287F876F
7 changed files with 102 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.github/CONTRIBUTING.md vendored
View File

@ -3,23 +3,21 @@
If the app is not behaving like it should, it's not necessarily a bug. Please consult the following resources before
submitting a new issue.
* [User Manual](https://docs.k9mail.app/)
* [Frequently Asked Questions](https://forum.k9mail.app/c/faq)
* [Support Forum](https://forum.k9mail.app/)
- [User Manual](https://docs.k9mail.app/)
- [Frequently Asked Questions](https://forum.k9mail.app/c/faq)
- [Support Forum](https://forum.k9mail.app/)
### Bug report guidelines
* The issue tracker is solely for bug reports and feature/enhancement requests. If you have a question of any kind,
please use the [support forum](https://forum.k9mail.app/c/support) instead.
* Search the [existing issues](https://github.com/thundernest/k-9/issues?q=) first to make sure your issue hasn't been
reported before.
- The issue tracker is solely for bug reports and feature/enhancement requests. If you have a question of any kind,
please use the [support forum](https://forum.k9mail.app/c/support) instead.
- Search the [existing issues](https://github.com/thundernest/k-9/issues?q=) first to make sure your issue hasn't been
reported before.
## Translations
We're using [Transifex](https://www.transifex.com/k-9/k9mail/) to manage translations.
## Contributing code
We love [pull requests](https://github.com/thundernest/k-9/pulls) from everyone!

16
.github/pull_request_template.md vendored
View File

@ -1,12 +1,12 @@
Please ensure that your pull request meets the following requirements - thanks!
* Does not contain merge commits. Rebase instead.
* Contains commits with descriptive titles.
* New code is written in Kotlin whenever possible.
* Follows our existing codestyle (`gradlew ktlintCheck`; will be checked by CI).
* Does not break any unit tests (`gradlew testDebugUnitTest`; will be checked by CI).
* Uses a descriptive title; don't put issue numbers in there.
* Contains a reference to the issue that it fixes (e.g. *Closes #XXX* or *Fixes #XXX*) in the body text.
* For cosmetic changes add one or multiple images, if possible.
- Does not contain merge commits. Rebase instead.
- Contains commits with descriptive titles.
- New code is written in Kotlin whenever possible.
- Follows our existing codestyle (`gradlew ktlintCheck`; will be checked by CI).
- Does not break any unit tests (`gradlew testDebugUnitTest`; will be checked by CI).
- Uses a descriptive title; don't put issue numbers in there.
- Contains a reference to the issue that it fixes (e.g. _Closes #XXX_ or _Fixes #XXX_) in the body text.
- For cosmetic changes add one or multiple images, if possible.
Finally, please replace this template text with a description of the change and additional context if necessary.

11
README.md
View File

@ -1,10 +1,10 @@
# K-9 Mail
[![Latest release](https://img.shields.io/github/release/thundernest/k-9.svg?style=flat-square)](https://github.com/thundernest/k-9/releases/latest)
[![Latest beta release](https://img.shields.io/github/v/release/thundernest/k-9.svg?include_prereleases&style=flat-square)](https://github.com/thundernest/k-9/releases)
K-9 Mail is an open-source email client for Android.
## Download
K-9 Mail can be downloaded from a couple of sources:
@ -15,13 +15,11 @@ K-9 Mail can be downloaded from a couple of sources:
You might also be interested in becoming a [tester](https://forum.k9mail.app/t/how-do-i-become-a-beta-tester/68) to get an early look at new versions.
## Release Notes
Check out the [Release Notes](https://github.com/thundernest/k-9/wiki/ReleaseNotes) to find out what changed
in each version of K-9 Mail.
## Need Help?
If the app is not behaving like it should, you might find these resources helpful:
@ -30,18 +28,15 @@ If the app is not behaving like it should, you might find these resources helpfu
- [Frequently Asked Questions](https://forum.k9mail.app/c/faq)
- [Support Forum](https://forum.k9mail.app/)
## Translations
Interested in helping to translate K-9 Mail? Contribute here:
https://www.transifex.com/projects/p/k9mail/
## Contributing
Thank you for contributing! If you're unfamiliar with the code,
start by reading the [developer documentation](docs/DESIGN.md)
Thank you for contributing! If you're unfamiliar with the code, start by reading the [developer documentation](docs/DESIGN.md)
Please fork this repository and contribute back using [pull requests](https://github.com/thundernest/k-9/pulls).
@ -49,7 +44,6 @@ Any contributions, large or small, major features, bug fixes, unit/integration t
but will be thoroughly reviewed and discussed.
Please make sure you read the [Code Style Guidelines](https://github.com/thundernest/k-9/wiki/CodeStyle).
## Communication
Aside from discussing changes in [pull requests](https://github.com/thundernest/k-9/pulls) and
@ -59,7 +53,6 @@ Aside from discussing changes in [pull requests](https://github.com/thundernest/
- IRC: [#k9mail on Libera Chat](https://web.libera.chat/#k9mail)
- [Developer mailing list](https://groups.google.com/forum/#!forum/k-9-dev)
## License
Licensed under the Apache License, Version 2.0 (the "License");

2
cli/html-cleaner-cli/README.md
View File

@ -12,6 +12,6 @@ Arguments:
OUTPUT Output file
```
You can run this tool using the [html-cleaner](../../html-cleaner) script in the root directory of this repository.
You can run this tool using the [html-cleaner](../../html-cleaner) script in the root directory of this repository.
It will compile the application and then run it using the given arguments. This allows you to make modifications to the
[HTML cleaning code](../../app/html-cleaner/src/main/java/app/k9mail/html/cleaner) and test the changes right away.

2
docs/DESIGN.md
View File

@ -23,7 +23,7 @@ Additional, standalone, libraries used by K-9
# Walkthrough
To help you understand the design, the following sequence diagrams show typical flows through the
classes. Each class is colour-coded by its top-level project.
classes. Each class is colour-coded by its top-level project.
## Reading email

70
plugins/openpgp-api-lib/CHANGELOG.md
View File

@ -1,48 +1,56 @@
# Version history
## Version 10
* Retrieve whole public key via ACTION_GET_KEY
- Retrieve whole public key via ACTION_GET_KEY
## Version 9
* AIDL Service has been changed from IOpenPgpService.aidl to IOpenPgpService2.aidl
This fixes truncated data streams (thanks to 'mgeier63').
* Fix for OpenPgpKeyPreference: Properly execute pending user interactions
* Charset moved to OpenPgpMetadata
- AIDL Service has been changed from IOpenPgpService.aidl to IOpenPgpService2.aidl
This fixes truncated data streams (thanks to 'mgeier63').
- Fix for OpenPgpKeyPreference: Properly execute pending user interactions
- Charset moved to OpenPgpMetadata
## Version 8
* OpenPgpSignatureResult:
method getStatus() renamed to getResult()
constants have been renamed for clarity
new constants: RESULT_NO_SIGNATURE, RESULT_INVALID_INSECURE
isSignatureOnly() has been deprecated
* RESULT_TYPES have been removed
* new OpenPgpDecryptionResult returned via RESULT_DECRYPTION
* OpenPgpSignatureResult and OpenPgpDecryptionResult are never null, they are always returned.
- OpenPgpSignatureResult:
method getStatus() renamed to getResult()
constants have been renamed for clarity
new constants: RESULT_NO_SIGNATURE, RESULT_INVALID_INSECURE
isSignatureOnly() has been deprecated
- RESULT_TYPES have been removed
- new OpenPgpDecryptionResult returned via RESULT_DECRYPTION
- OpenPgpSignatureResult and OpenPgpDecryptionResult are never null, they are always returned.
## Version 7
* Deprecation of ACCOUNT_NAME, please use ACTION_GET_SIGN_KEY_ID to get key id
* Introduce EXTRA_SIGN_KEY_ID
* New extra for ACTION_ENCRYPT and ACTION_SIGN_AND_ENCRYPT: EXTRA_ENABLE_COMPRESSION (default to true)
* Return PendingIntent to view key for signatures
* New result for ACTION_DECRYPT_VERIFY: RESULT_TYPE
* New ACTION_GET_SIGN_KEY_ID
* EXTRA_PASSPHRASE changed from String to char[]
- Deprecation of ACCOUNT_NAME, please use ACTION_GET_SIGN_KEY_ID to get key id
- Introduce EXTRA_SIGN_KEY_ID
- New extra for ACTION_ENCRYPT and ACTION_SIGN_AND_ENCRYPT: EXTRA_ENABLE_COMPRESSION (default to true)
- Return PendingIntent to view key for signatures
- New result for ACTION_DECRYPT_VERIFY: RESULT_TYPE
- New ACTION_GET_SIGN_KEY_ID
- EXTRA_PASSPHRASE changed from String to char[]
## Version 6
* Deprecate ACTION_SIGN
* Introduce ACTION_CLEARTEXT_SIGN and ACTION_DETACHED_SIGN
* New extra for ACTION_DETACHED_SIGN: EXTRA_DETACHED_SIGNATURE
* New result for ACTION_DECRYPT_VERIFY: RESULT_DETACHED_SIGNATURE
* New result for ACTION_DECRYPT_VERIFY: RESULT_CHARSET
- Deprecate ACTION_SIGN
- Introduce ACTION_CLEARTEXT_SIGN and ACTION_DETACHED_SIGN
- New extra for ACTION_DETACHED_SIGN: EXTRA_DETACHED_SIGNATURE
- New result for ACTION_DECRYPT_VERIFY: RESULT_DETACHED_SIGNATURE
- New result for ACTION_DECRYPT_VERIFY: RESULT_CHARSET
## Version 5
* OpenPgpSignatureResult: new consts RESULT_INVALID_KEY_REVOKED and RESULT_INVALID_KEY_EXPIRED
* OpenPgpSignatureResult: ArrayList<String> userIds
- OpenPgpSignatureResult: new consts RESULT_INVALID_KEY_REVOKED and RESULT_INVALID_KEY_EXPIRED
- OpenPgpSignatureResult: ArrayList<String> userIds
## Version 4
* No changes to existing methods -> backward compatible
* Introduction of ACTION_DECRYPT_METADATA, RESULT_METADATA, EXTRA_ORIGINAL_FILENAME, and OpenPgpMetadata parcel
* Introduction of internal NFC extras: EXTRA_NFC_SIGNED_HASH, EXTRA_NFC_SIG_CREATION_TIMESTAMP
- No changes to existing methods -> backward compatible
- Introduction of ACTION_DECRYPT_METADATA, RESULT_METADATA, EXTRA_ORIGINAL_FILENAME, and OpenPgpMetadata parcel
- Introduction of internal NFC extras: EXTRA_NFC_SIGNED_HASH, EXTRA_NFC_SIG_CREATION_TIMESTAMP
## Version 3
* First public stable version
- First public stable version

79
plugins/openpgp-api-lib/README.md
View File

@ -5,11 +5,13 @@ The OpenPGP API provides methods to execute OpenPGP operations, such as sign, en
### News
#### Version 10
* Retrieve whole public key via ACTION_GET_KEY
- Retrieve whole public key via ACTION_GET_KEY
[Full changelog here…](https://github.com/open-keychain/openpgp-api/blob/master/CHANGELOG.md)
### License
While OpenKeychain itself is GPLv3+, the API library is licensed under Apache License v2.
Thus, you are allowed to also use it in closed source applications as long as you respect the [Apache License v2](https://github.com/open-keychain/openpgp-api/blob/master/LICENSE).
@ -28,7 +30,8 @@ dependencies {
```
### Full example
A full working example is available in the [example project](https://github.com/open-keychain/openpgp-api/blob/master/example). The [``OpenPgpApiActivity.java``](https://github.com/open-keychain/openpgp-api/blob/master/example/src/main/java/org/openintents/openpgp/example/OpenPgpApiActivity.java) contains most relevant sourcecode.
A full working example is available in the [example project](https://github.com/open-keychain/openpgp-api/blob/master/example). The [`OpenPgpApiActivity.java`](https://github.com/open-keychain/openpgp-api/blob/master/example/src/main/java/org/openintents/openpgp/example/OpenPgpApiActivity.java) contains most relevant sourcecode.
### API
@ -38,21 +41,24 @@ A full working example is available in the [example project](https://github.com/
**This tutorial only covers the basics, please consult the full example for a complete overview over all methods**
The API is **not** designed around ``Intents`` which are started via ``startActivityForResult``. These Intent actions typically start an activity for user interaction, so they are not suitable for background tasks. Most API design decisions are explained at [the bottom of this wiki page](https://github.com/open-keychain/open-keychain/wiki/OpenPGP-API#internal-design-decisions).
The API is **not** designed around `Intents` which are started via `startActivityForResult`. These Intent actions typically start an activity for user interaction, so they are not suitable for background tasks. Most API design decisions are explained at [the bottom of this wiki page](https://github.com/open-keychain/open-keychain/wiki/OpenPGP-API#internal-design-decisions).
We will go through the basic steps to understand how this API works, following this (greatly simplified) sequence diagram:
![](https://github.com/open-keychain/open-keychain/raw/master/Resources/docs/openpgp_api_1.jpg)
In this diagram the client app is depicted on the left side, the OpenPGP provider (in this case OpenKeychain) is depicted on the right.
The remote service is defined via the [AIDL](http://developer.android.com/guide/components/aidl.html) file [``IOpenPgpService``](https://github.com/open-keychain/openpgp-api/blob/master/openpgp-api/src/main/aidl/org/openintents/openpgp/IOpenPgpService.aidl).
The remote service is defined via the [AIDL](http://developer.android.com/guide/components/aidl.html) file [`IOpenPgpService`](https://github.com/open-keychain/openpgp-api/blob/master/openpgp-api/src/main/aidl/org/openintents/openpgp/IOpenPgpService.aidl).
It contains only one exposed method which can be invoked remotely:
```java
interface IOpenPgpService {
Intent execute(in Intent data, in ParcelFileDescriptor input, in ParcelFileDescriptor output);
}
```
The interaction between the apps is done by binding from your client app to the remote service of OpenKeychain.
``OpenPgpServiceConnection`` is a helper class from the library to ease this step:
`OpenPgpServiceConnection` is a helper class from the library to ease this step:
```java
OpenPgpServiceConnection mServiceConnection;
@ -72,36 +78,38 @@ public void onDestroy() {
Following the sequence diagram, these steps are executed:
1. Define an ``Intent`` containing the actual PGP instructions which should be done, e.g.
```java
1. Define an `Intent` containing the actual PGP instructions which should be done, e.g.
`java
Intent data = new Intent();
data.setAction(OpenPgpApi.ACTION_ENCRYPT);
data.putExtra(OpenPgpApi.EXTRA_USER_IDS, new String[]{"dominik@dominikschuermann.de"});
data.putExtra(OpenPgpApi.EXTRA_REQUEST_ASCII_ARMOR, true);
```
Define an ``InputStream`` currently holding the plaintext, and an ``OutputStream`` where you want the ciphertext to be written by OpenKeychain's remote service:
```java
`
Define an `InputStream` currently holding the plaintext, and an `OutputStream` where you want the ciphertext to be written by OpenKeychain's remote service:
`java
InputStream is = new ByteArrayInputStream("Hello world!".getBytes("UTF-8"));
ByteArrayOutputStream os = new ByteArrayOutputStream();
```
Using a helper class from the library, ``is`` and ``os`` are passed via ``ParcelFileDescriptors`` as ``input`` and ``output`` together with ``Intent data``, as depicted in the sequence diagram, from the client to the remote service.
`
Using a helper class from the library, `is` and `os` are passed via `ParcelFileDescriptors` as `input` and `output` together with `Intent data`, as depicted in the sequence diagram, from the client to the remote service.
Programmatically, this can be done with:
```java
`java
OpenPgpApi api = new OpenPgpApi(this, mServiceConnection.getService());
Intent result = api.executeApi(data, is, os);
```
`
2. The PGP operation is executed by OpenKeychain and the produced ciphertext is written into ``os`` which can then be accessed by the client app.
2. The PGP operation is executed by OpenKeychain and the produced ciphertext is written into `os` which can then be accessed by the client app.
3. A result Intent is returned containing one of these result codes:
* ``OpenPgpApi.RESULT_CODE_ERROR``
* ``OpenPgpApi.RESULT_CODE_SUCCESS``
* ``OpenPgpApi.RESULT_CODE_USER_INTERACTION_REQUIRED``
If ``RESULT_CODE_USER_INTERACTION_REQUIRED`` is returned, an additional ``PendingIntent`` is returned to the client, which must be used to get user input required to process the request.
A ``PendingIntent`` is executed with ``startIntentSenderForResult``, which starts an activity, originally belonging to OpenKeychain, on the [task stack](http://developer.android.com/guide/components/tasks-and-back-stack.html) of the client.
Only if ``RESULT_CODE_SUCCESS`` is returned, ``os`` actually contains data.
- `OpenPgpApi.RESULT_CODE_ERROR`
- `OpenPgpApi.RESULT_CODE_SUCCESS`
- `OpenPgpApi.RESULT_CODE_USER_INTERACTION_REQUIRED`
If `RESULT_CODE_USER_INTERACTION_REQUIRED` is returned, an additional `PendingIntent` is returned to the client, which must be used to get user input required to process the request.
A `PendingIntent` is executed with `startIntentSenderForResult`, which starts an activity, originally belonging to OpenKeychain, on the [task stack](http://developer.android.com/guide/components/tasks-and-back-stack.html) of the client.
Only if `RESULT_CODE_SUCCESS` is returned, `os` actually contains data.
A nearly complete example looks like this:
```java
switch (result.getIntExtra(OpenPgpApi.RESULT_CODE, OpenPgpApi.RESULT_CODE_ERROR)) {
case OpenPgpApi.RESULT_CODE_SUCCESS: {
@ -135,10 +143,10 @@ Intent result = api.executeApi(data, is, os);
}
```
4. Results from a ``PendingIntent`` are returned in ``onActivityResult`` of the activity, which executed ``startIntentSenderForResult``.
The returned ``Intent data`` in ``onActivityResult`` contains the original PGP operation definition and new values acquired from the user interaction.
Thus, you can now execute the ``Intent`` again, like done in step 1.
This time it should return with ``RESULT_CODE_SUCCESS`` because all required information has been obtained by the previous user interaction stored in this ``Intent``.
4. Results from a `PendingIntent` are returned in `onActivityResult` of the activity, which executed `startIntentSenderForResult`.
The returned `Intent data` in `onActivityResult` contains the original PGP operation definition and new values acquired from the user interaction.
Thus, you can now execute the `Intent` again, like done in step 1.
This time it should return with `RESULT_CODE_SUCCESS` because all required information has been obtained by the previous user interaction stored in this `Intent`.
```java
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
[...]
@ -154,16 +162,17 @@ Intent result = api.executeApi(data, is, os);
}
```
### Tipps
* ``api.executeApi(data, is, os);`` is a blocking call. If you want a convenient asynchronous call, use ``api.executeApiAsync(data, is, os, new MyCallback([... ]));``, where ``MyCallback`` is an private class implementing ``OpenPgpApi.IOpenPgpCallback``.
See [``OpenPgpApiActivity.java``](https://github.com/open-keychain/openpgp-api/blob/master/example/src/main/java/org/openintents/openpgp/example/OpenPgpApiActivity.java) for an example.
* Using
```java
mServiceConnection = new OpenPgpServiceConnection(this, "org.sufficientlysecure.keychain");
```
connects to OpenKeychain directly.
If you want to let the user choose between OpenPGP providers, you can implement the [``OpenPgpAppPreference.java``](https://github.com/open-keychain/openpgp-api/tree/master/openpgp-api/src/main/java/org/openintents/openpgp/util/OpenPgpAppPreference.java) like done in the example app.
- `api.executeApi(data, is, os);` is a blocking call. If you want a convenient asynchronous call, use `api.executeApiAsync(data, is, os, new MyCallback([... ]));`, where `MyCallback` is an private class implementing `OpenPgpApi.IOpenPgpCallback`.
See [`OpenPgpApiActivity.java`](https://github.com/open-keychain/openpgp-api/blob/master/example/src/main/java/org/openintents/openpgp/example/OpenPgpApiActivity.java) for an example.
- Using
* To enable installing a debug and release version at the same time, the `debug` build of OpenKeychain uses `org.sufficientlysecure.keychain.debug` as a package name. Make sure you connect to the right one during development!
```java
mServiceConnection = new OpenPgpServiceConnection(this, "org.sufficientlysecure.keychain");
```
connects to OpenKeychain directly.
If you want to let the user choose between OpenPGP providers, you can implement the [`OpenPgpAppPreference.java`](https://github.com/open-keychain/openpgp-api/tree/master/openpgp-api/src/main/java/org/openintents/openpgp/util/OpenPgpAppPreference.java) like done in the example app.
- To enable installing a debug and release version at the same time, the `debug` build of OpenKeychain uses `org.sufficientlysecure.keychain.debug` as a package name. Make sure you connect to the right one during development!