<commit_before># Contributing to F-Droid Data

For information about all aspects of F-Droid, check out the [documentation](https://f-droid.org/docs).


## Issue Tracker

### Inclusion of new apps

If you are a "first time" contributor, consider opening an issue at
[RFP (Request for Packaging)](https://gitlab.com/fdroid/rfp/-/issues).
Don't forget to fill in the issue template.

### Updating apps already in F-Droid

You may use the [issue tracker](https://gitlab.com/fdroid/fdroiddata/issues) to report
issues on app metadata or issues with the packages distributed through our repository.
For instance:
- an app is outdated
- an app has Antifeatures, but they are not listed in the app or on the website.

Before opening an issue about an outdated app, have a look at its metadata
file and make sure that updating the app is actually possible. For example,
`MaintainerNotes` might contain a hint on why it's impossible to further update
an app (e.g. proprietary dependencies were added, essential parts of the code
are no longer available).

Also make sure having checked with already existing issues (including closed ones)
which might give similar explanations.

## Merge Requests

### Setting up fdroiddata for merge requests

- [Register on GitLab](https://gitlab.com/).
- Visit and fork the [fdroiddata repository](https://gitlab.com/fdroid/fdroiddata).

App metadata for a merge request can be created without or with the use of `fdroidserver`.
The latter is only recommended for really advanced users.

### Metadata preparation without fdroidserver

You can either write the metadata file locally, on your machine, or directly on the GitLab website.
Please read the [General Recommendations](#general-recommendations) before you start.

#### On the GitLab website

1. Visit your fork.
1. Create a new branch.
   Naming it like the app name or, much better, the app id makes it easier to keep track of your contributions.
1. Visit the `metadata` directory of your fork.
1. Add a new file by clicking on the plus sign and choosing _"New file"_.
1. Set the file name in the following schema: `<application_id>.yml`. So an example would be _"com.app.example.yml"_.
1. Write down the metadata. The [Build Metadata Reference](https://f-droid.org/en/docs/Build_Metadata_Reference)
   as well as the [templates from the wiki](https://gitlab.com/fdroid/wiki/-/wikis/Metadata/YAML-Metadata)
   will help you.
1. Choose a smart commit message and commit your changes.
1. Continue with the [Common steps for both methods](#common-steps-for-both-methods)

#### On your local machine

1. Clone your fork.
1. Create and checkout a new branch.
   Naming it like the app name or, much better, the app id makes it easier to keep track of your contributions.
1. Create a new file in the the `metadata` directory named after the following schema: `<application_id>.yml`.
   So an example would be _"com.app.example.yml"_.
1. Write down the metadata in that file. The [Build Metadata Reference](https://f-droid.org/en/docs/Build_Metadata_Reference)
   as well as the [templates from the wiki](https://gitlab.com/fdroid/wiki/-/wikis/Metadata/YAML-Metadata)
   will help you.
1. Commit and push to your upstream fork.
1. Continue with the [Common steps for both methods](#common-steps-for-both-methods)

#### Common steps for both methods

1. Go to the `CI/CD` menu in the GitLab project of your fork.
1. Check if the pipeline for your commit(s) succeed.
   If not, take a look into the logs and try to fix the error by editing the metadata file again.
1. If everything went fine, you can create a
   new [merge request](https://gitlab.com/fdroid/fdroiddata/-/merge_requests) at the `fdroiddata` repository.
1. Now wait for the packagers to pick up your Merge Request. Please keep track if they asked any questions
   and reply to them as soon as possible.

### Metadata preparation with fdroidserver

Please read the [General Recommendations](#general-recommendations) before you start.

#### Setting up fdroidserver

> Note that to use the `master` branch of _fdroiddata_ you will need the
master branch of _fdroidserver_. Using the latest stable release of
fdroidserver would probably work, but it is not guaranteed.

Install [fdroidserver](https://gitlab.com/fdroid/fdroidserver), or just
use it directly from master:
```shell
git clone https://gitlab.com/fdroid/fdroidserver.git
export PATH="$PATH:$PWD/fdroidserver"
```

Clone your fork of fdroiddata and enter it:
```shell
git clone https://gitlab.com/YOUR_USERNAME/fdroiddata.git
cd fdroiddata
```

Make sure fdroid works and reads the metadata files properly:
```shell
fdroid readmeta
```

#### Adding a new app

If you want to add a new app you will have to add a new metadata file to the
repository, like `metadata/app.id.yml`. Here is how to write that file.

If the app is on GitHub or any GitLab or Gitea/Gogs instance, you can use `fdroid import`.
However, the metadata fields `IssueTracker` and `SourceCode` will only be generated, if the source code
is hosted on one of the following platforms:

- GitHub 
- GitLab
- FramaGit
- NotABug
- Bitbucket
- Codeberg

If the source code is **not** on one of those you **must** add `.git` to the end of the URL.

```shell
fdroid import --url https://github.com/foo/bar --subdir app
```<commit_msg>Suggest installing fdroidserver with pip in CONTRIBUTING.md<commit_after># Contributing to F-Droid Data

For information about all aspects of F-Droid, check out the [documentation](https://f-droid.org/docs).


## Issue Tracker

### Inclusion of new apps

If you are a "first time" contributor, consider opening an issue at
[RFP (Request for Packaging)](https://gitlab.com/fdroid/rfp/-/issues).
Don't forget to fill in the issue template.

### Updating apps already in F-Droid

You may use the [issue tracker](https://gitlab.com/fdroid/fdroiddata/issues) to report
issues on app metadata or issues with the packages distributed through our repository.
For instance:
- an app is outdated
- an app has Antifeatures, but they are not listed in the app or on the website.

Before opening an issue about an outdated app, have a look at its metadata
file and make sure that updating the app is actually possible. For example,
`MaintainerNotes` might contain a hint on why it's impossible to further update
an app (e.g. proprietary dependencies were added, essential parts of the code
are no longer available).

Also make sure having checked with already existing issues (including closed ones)
which might give similar explanations.

## Merge Requests

### Setting up fdroiddata for merge requests

- [Register on GitLab](https://gitlab.com/).
- Visit and fork the [fdroiddata repository](https://gitlab.com/fdroid/fdroiddata).

App metadata for a merge request can be created without or with the use of `fdroidserver`.
The latter is only recommended for really advanced users.

### Metadata preparation without fdroidserver

You can either write the metadata file locally, on your machine, or directly on the GitLab website.
Please read the [General Recommendations](#general-recommendations) before you start.

#### On the GitLab website

1. Visit your fork.
1. Create a new branch.
   Naming it like the app name or, much better, the app id makes it easier to keep track of your contributions.
1. Visit the `metadata` directory of your fork.
1. Add a new file by clicking on the plus sign and choosing _"New file"_.
1. Set the file name in the following schema: `<application_id>.yml`. So an example would be _"com.app.example.yml"_.
1. Write down the metadata. The [Build Metadata Reference](https://f-droid.org/en/docs/Build_Metadata_Reference)
   as well as the [templates from the wiki](https://gitlab.com/fdroid/wiki/-/wikis/Metadata/YAML-Metadata)
   will help you.
1. Choose a smart commit message and commit your changes.
1. Continue with the [Common steps for both methods](#common-steps-for-both-methods)

#### On your local machine

1. Clone your fork.
1. Create and checkout a new branch.
   Naming it like the app name or, much better, the app id makes it easier to keep track of your contributions.
1. Create a new file in the the `metadata` directory named after the following schema: `<application_id>.yml`.
   So an example would be _"com.app.example.yml"_.
1. Write down the metadata in that file. The [Build Metadata Reference](https://f-droid.org/en/docs/Build_Metadata_Reference)
   as well as the [templates from the wiki](https://gitlab.com/fdroid/wiki/-/wikis/Metadata/YAML-Metadata)
   will help you.
1. Commit and push to your upstream fork.
1. Continue with the [Common steps for both methods](#common-steps-for-both-methods)

#### Common steps for both methods

1. Go to the `CI/CD` menu in the GitLab project of your fork.
1. Check if the pipeline for your commit(s) succeed.
   If not, take a look into the logs and try to fix the error by editing the metadata file again.
1. If everything went fine, you can create a
   new [merge request](https://gitlab.com/fdroid/fdroiddata/-/merge_requests) at the `fdroiddata` repository.
1. Now wait for the packagers to pick up your Merge Request. Please keep track if they asked any questions
   and reply to them as soon as possible.

### Metadata preparation with fdroidserver

Please read the [General Recommendations](#general-recommendations) before you start.

#### Setting up fdroidserver

Install [F-Droid Server](https://gitlab.com/fdroid/fdroidserver):
```shell
pip install git+https://gitlab.com/fdroid/fdroidserver.git
```

Clone your fork of [F-Droid Data](https://gitlab.com/fdroid/fdroiddata/) and enter it:
```shell
git clone https://gitlab.com/YOUR_USERNAME/fdroiddata.git
cd fdroiddata
```

Make sure `fdroid` works and reads the metadata files properly:
```shell
fdroid readmeta
```

#### Adding a new app

If you want to add a new app you will have to add a new metadata file to the
repository, like `metadata/app.id.yml`. Here is how to write that file.

If the app is on GitHub or any GitLab or Gitea/Gogs instance, you can use `fdroid import`.
However, the metadata fields `IssueTracker` and `SourceCode` will only be generated, if the source code
is hosted on one of the following platforms:

- GitHub 
- GitLab
- FramaGit
- NotABug
- Bitbucket
- Codeberg

If the source code is **not** on one of those you **must** add `.git` to the end of the URL.

```shell
fdroid import --url https://github.com/foo/bar --subdir app
```
{'fraction_non_alphanumeric': 0.08445426594926979, 'fraction_numerical': 0.0034588777863182167, 'mean_word_length': 4.1478733926805145, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 8, 'https://': 29, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1723806', 'n_tokens_mistral': 2993, 'n_tokens_neox': 2891, 'n_words': 1433}