2021-06-08 18:16:59 +02:00
|
|
|
# Contributing to F-Droid Data
|
2014-04-12 18:26:56 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
For information about all aspects of F-Droid, check out the [documentation](https://f-droid.org/docs).
|
2017-12-12 22:12:35 +01:00
|
|
|
|
2014-04-12 18:26:56 +02:00
|
|
|
|
2017-12-12 22:12:35 +01:00
|
|
|
## Issue Tracker
|
2014-08-07 01:12:46 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
### 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.
|
2015-08-19 01:02:24 +02:00
|
|
|
|
2015-08-19 01:55:47 +02:00
|
|
|
Before opening an issue about an outdated app, have a look at its metadata
|
2021-06-08 18:16:59 +02:00
|
|
|
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).
|
2017-12-12 22:12:35 +01:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
Also make sure having checked with already existing issues (including closed ones)
|
|
|
|
which might give similar explanations.
|
2014-08-07 01:12:46 +02:00
|
|
|
|
|
|
|
## Merge Requests
|
|
|
|
|
2015-08-19 01:55:47 +02:00
|
|
|
### Setting up fdroiddata for merge requests
|
2015-08-19 01:02:24 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
- [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)
|
2023-01-01 13:09:30 +01:00
|
|
|
as well as the [templates](./templates/README.md)
|
2021-06-08 18:16:59 +02:00
|
|
|
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)
|
2015-08-19 01:02:24 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
#### On your local machine
|
2015-08-19 01:55:47 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
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)
|
2023-01-01 13:09:30 +01:00
|
|
|
as well as the [templates](./templates/README.md)
|
2021-06-08 18:16:59 +02:00
|
|
|
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)
|
2016-01-17 20:02:32 +01:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
#### Common steps for both methods
|
2016-01-17 20:02:32 +01:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
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
|
2021-08-16 06:22:32 +02:00
|
|
|
new [merge request](https://gitlab.com/fdroid/fdroiddata/-/merge_requests) at the `fdroiddata` repository.
|
2021-06-08 18:16:59 +02:00
|
|
|
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
|
|
|
|
|
2022-04-15 15:28:23 +02:00
|
|
|
Install [F-Droid Server](https://gitlab.com/fdroid/fdroidserver):
|
2021-06-08 18:16:59 +02:00
|
|
|
```shell
|
2022-04-15 15:28:23 +02:00
|
|
|
pip install git+https://gitlab.com/fdroid/fdroidserver.git
|
2021-06-08 18:16:59 +02:00
|
|
|
```
|
|
|
|
|
2022-04-15 15:28:23 +02:00
|
|
|
Clone your fork of [F-Droid Data](https://gitlab.com/fdroid/fdroiddata/) and enter it:
|
2021-06-08 18:16:59 +02:00
|
|
|
```shell
|
|
|
|
git clone https://gitlab.com/YOUR_USERNAME/fdroiddata.git
|
|
|
|
cd fdroiddata
|
|
|
|
```
|
|
|
|
|
2022-04-15 15:28:23 +02:00
|
|
|
Make sure `fdroid` works and reads the metadata files properly:
|
2021-06-08 18:16:59 +02:00
|
|
|
```shell
|
|
|
|
fdroid readmeta
|
|
|
|
```
|
|
|
|
|
|
|
|
#### Adding a new app
|
2015-08-19 01:55:47 +02:00
|
|
|
|
|
|
|
If you want to add a new app you will have to add a new metadata file to the
|
2019-02-06 17:26:14 +01:00
|
|
|
repository, like `metadata/app.id.yml`. Here is how to write that file.
|
2015-08-19 01:55:47 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
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:
|
2015-08-19 01:55:47 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
- GitHub
|
|
|
|
- GitLab
|
|
|
|
- FramaGit
|
|
|
|
- NotABug
|
|
|
|
- Bitbucket
|
|
|
|
- Codeberg
|
2015-08-19 01:55:47 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
If the source code is **not** on one of those you **must** add `.git` to the end of the URL.
|
2015-08-19 01:55:47 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
```shell
|
|
|
|
fdroid import --url https://github.com/foo/bar --subdir app
|
|
|
|
```
|
2015-08-19 01:55:47 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
Alternatively, start the metadata file from scratch, see [the templates](https://gitlab.com/fdroid/fdroiddata/tree/master/templates):
|
|
|
|
```shell
|
2023-01-16 03:50:34 +01:00
|
|
|
cp templates/general.yml metadata/app.id.yml
|
2021-06-08 18:16:59 +02:00
|
|
|
```
|
2018-08-17 17:46:23 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
Or by download:
|
|
|
|
```shell
|
2023-01-16 03:50:34 +01:00
|
|
|
wget -O metadata/app.id.yml https://gitlab.com/fdroid/fdroiddata/raw/master/templates/general.yml
|
2021-06-08 18:16:59 +02:00
|
|
|
```
|
2018-08-17 17:46:23 +02:00
|
|
|
|
2015-08-19 01:55:47 +02:00
|
|
|
Now that the file is created, you need to fill up all the app information and
|
|
|
|
add a working build recipe.
|
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
You can use the [metadata section](https://f-droid.org/docs/Build_Metadata_Reference)
|
2023-01-16 03:50:34 +01:00
|
|
|
in the documentation for reference, or the full template at `templates/general.yml` for
|
2015-08-19 01:55:47 +02:00
|
|
|
some suggestions.
|
2015-08-19 01:02:24 +02:00
|
|
|
|
2015-08-20 02:50:27 +02:00
|
|
|
Once you're done, see if `fdroid readmeta` runs without any errors. If it
|
|
|
|
doesn't, there are syntax errors in your metadata file.
|
2015-08-19 01:02:24 +02:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
#### Building it
|
2015-08-19 02:18:35 +02:00
|
|
|
|
|
|
|
We build apps from source, so a new app must have at least one working build.
|
|
|
|
|
|
|
|
You can have a look at the build templates at `templates/build-*` for some
|
2021-06-08 18:16:59 +02:00
|
|
|
quick suggestions. You may also follow the documentation or look at how other apps
|
2015-08-19 02:18:35 +02:00
|
|
|
are built for working examples.
|
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
- Run `fdroid readmeta` again to make sure there still aren't any syntax errors
|
|
|
|
- Run `fdroid rewritemeta app.id` to clean up your file
|
|
|
|
- Run `fdroid checkupdates app.id` to fill automated fields like `Auto Name` and `Current Version`
|
|
|
|
- Make sure that `fdroid lint app.id` doesn't report any warnings. If it does, fix them.
|
|
|
|
- Test your build recipe with `fdroid build -v -l app.id`
|
2015-08-19 01:02:24 +02:00
|
|
|
|
2015-08-19 01:55:47 +02:00
|
|
|
Congratulations! You can now open a merge request to add your app.
|
2015-08-19 01:02:24 +02:00
|
|
|
|
2015-08-19 02:13:47 +02:00
|
|
|
### General recommendations
|
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
- Keep a separate branch for every app you want to submit.
|
|
|
|
- Keep your forks `master` branch up-to-date. For more information see here:
|
|
|
|
https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin
|
|
|
|
- As a result of the two tips above, you should **not** commit to your `master` branch.
|
|
|
|
This will also trigger new pipelines at the right time.
|
|
|
|
- Do not open a Merge Request from a protected branch.
|
|
|
|
The `master` branch is protected by default, but other branches can also be protected.
|
|
|
|
- Fill the template when opening a new Merge Request.
|
|
|
|
- [Squash](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html)
|
|
|
|
your commits. (enabled by default)
|
2018-08-24 19:03:28 +02:00
|
|
|
|
|
|
|
### After You Added Your App
|
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
_"How long does it take for my app to show up in the F-Droid repository?"_ is a very frequently asked question.
|
|
|
|
Please take a look at
|
|
|
|
[the wiki](https://gitlab.com/fdroid/wiki/-/wikis/FAQ#how-long-does-it-take-for-my-app-to-show-up-on-website-and-client)
|
|
|
|
for the answer.
|
|
|
|
|
2018-08-24 19:24:36 +02:00
|
|
|
- If you have enabled [auto-updates], F-Droid will build new versions from tags
|
2018-08-24 19:03:28 +02:00
|
|
|
automatically.
|
|
|
|
|
|
|
|
```
|
2021-06-08 18:16:59 +02:00
|
|
|
AutoUpdateMode: Version
|
2019-02-06 17:42:21 +01:00
|
|
|
UpdateCheckMode: Tags
|
2018-08-24 19:03:28 +02:00
|
|
|
```
|
|
|
|
- You may like to add [localization and screenshots], so users can have a glance
|
|
|
|
at the app in pictures and in their preferred language.
|
|
|
|
- You can advertise the download of your app in this app store using the
|
2020-10-16 21:59:29 +02:00
|
|
|
[official graphic][get-it-on-fdroid].
|
2021-06-08 18:16:59 +02:00
|
|
|
|
2019-07-12 20:34:45 +02:00
|
|
|
<img src="https://fdroid.gitlab.io/artwork/badge/get-it-on.png" height="75">
|
2018-08-24 19:03:28 +02:00
|
|
|
|
|
|
|
```
|
2019-07-12 20:34:45 +02:00
|
|
|
<img src="https://fdroid.gitlab.io/artwork/badge/get-it-on.png" height="75">
|
2018-08-24 19:03:28 +02:00
|
|
|
```
|
2018-08-31 10:07:25 +02:00
|
|
|
- You can add a badge of your apps F-Droid version from [shields.io].
|
2021-06-08 18:16:59 +02:00
|
|
|
|
2022-08-21 16:59:39 +02:00
|
|
|
![](https://img.shields.io/badge/f--droid-v1.0-blue.svg?logo=F-Droid)
|
2018-08-31 10:07:25 +02:00
|
|
|
```
|
2022-08-21 16:59:39 +02:00
|
|
|
https://img.shields.io/f-droid/v/APP.ID.svg?logo=F-Droid
|
2018-08-31 10:07:25 +02:00
|
|
|
```
|
|
|
|
You can also include a GitHub release badge to know if your version is
|
|
|
|
up to date.
|
2021-06-08 18:16:59 +02:00
|
|
|
|
2018-08-31 10:07:25 +02:00
|
|
|
![Latest Release](https://img.shields.io/badge/release-v1.0-blue.svg?logo=github)
|
|
|
|
```
|
|
|
|
https://img.shields.io/github/release/USER/REPO.svg?logo=github
|
|
|
|
```
|
2018-08-24 19:03:28 +02:00
|
|
|
|
2019-11-28 10:13:00 +01:00
|
|
|
|
2021-06-08 18:16:59 +02:00
|
|
|
[localization and screenshots]: https://f-droid.org/docs/All_About_Descriptions_Graphics_and_Screenshots/
|
2018-08-24 19:03:28 +02:00
|
|
|
[get-it-on-fdroid]: https://f-droid.org/badge/get-it-on.png
|
2021-06-08 18:16:59 +02:00
|
|
|
[auto-updates]: https://f-droid.org/docs/Build_Metadata_Reference/#autoupdatemode
|
|
|
|
[shields.io]: https://shields.io/category/version
|