Commit 1e41bfca authored by Daniel Martí's avatar Daniel Martí

Rewrite CONTRIBUTING

parent 8fd75935
Pipeline #99449 passed with stage
# Contributing to F-Droid
Thanks so much for contributing to [F-Droid](https://f-droid.org)! Please take
your time to read carefully through this document:
## Issue Tracker
Please note that the tracker is not for app submissions, use the
[submission queue](https://f-droid.org/forums/forum/submission-queue/) instead.
For error reports please provide detailed system (e.g. Android version, used
ROM, hardware specifications) and error information (e.g. What happened? When
did it happen?) and provide the [logcat](https://developer.android.com/tools/help/logcat.html)
-- either by file upload or by inclduing it with the appropriated
[markdown](https://github.com/gitlabhq/gitlabhq/blob/master/doc/markdown/markdown.md).
You may use the issue tracker to report issues on app metadata and issues with
the packages distributed through our repository.
For update/change requests, please make sure they meet our
[inclusion policy](https://f-droid.org/wiki/page/Inclusion_Policy) and are not already
handled by our [submission queue](https://f-droid.org/forums/forum/submission-queue/),
are not [held](https://f-droid.org/forums/forum/submission-held/) for some reason or already
[marked for an update](https://f-droid.org/wiki/page/Category:Apps_to_Update).
Keep discussions to a minimum or use the forum instead.
Please note that app submissions belong in the
[submission queue](https://f-droid.org/forums/forum/submission-queue/).
However, the easiest way to get an app included, updated or an error fixed is
to provide the required metadata yourself by opening a merge request.
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. Issues opened
about apps that can no longer be built will be closed.
## Merge Requests
Please read through the [inclusion howto](https://f-droid.org/wiki/page/Inclusion_How-To),
the [inclusion policy](https://f-droid.org/wiki/page/Inclusion_Policy) and our
[fdroid manual](https://f-droid.org/manual/fdroid.html).
### General recommendations
* [Squash](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) your commits
### Setting up fdroidserver
* Clone [fdroidserver](https://gitlab.com/fdroid/fdroidserver):
This section includes some information on the fdroidserver repository as the
tools contained in there can be used standalone to check and build local
metadata files.
git clone https://gitlab.com/fdroid/fdroidserver
### Setting up fdroidserver and build tools
* Add the cloned dir to your `PATH`:
* Follow the instructions in [the manual](https://f-droid.org/manual).
export PATH="$PATH:~/fdroidserver
### Setting up fdroiddata and submitting apps
### Setting up fdroiddata for merge requests
* [Register on GitLab](http://gitlab.com)
* Visit and fork the [fdroiddata repository](https://gitlab.com/fdroid/fdroiddata/)
* Clone your fdroiddata fork
* Clone your fdroiddata fork:
git clone git@gitlab.com:username/fdroiddata.git
* Enter it:
cd fdroiddata
* An empty configuration file should work as a start:
touch config.py
* Make sure fdroid works and reads the metadata files properly:
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.txt`. Here is how to write that file.
* If the app is on GitHub, GitLab or Bitbucket, use `fdroid import`:
fdroid import --url https://github.com/foo/bar --subdir app
* Alternatively, start the metadata file from scratch:
cp templates/app-minimal metadata/app.id.txt
Now that the file is created, you need to fill up all the app information and
add a working build recipe.
You can use the [metadata section](https://f-droid.org/manual/html_node/Metadata.html)
in the manual for reference, or the full template at `templates/app-full` for
some suggestions.
* Copy fdroiddata/metadata/template or fdroiddata/metadata/template-minimal to
fdroiddata/metadata/app.id.txt
As for the build recipe, you can have a look at the build templates at
`templates/build-*` for some quick suggestions. Otherwise, follow the manual
and look at how other apps are built.
* Update metadata/app.id.txt according to the [manual](https://f-droid.org/manual/html_node/Metadata.html)
* Once you're done, see if `fdroid readmeta` runs without any errors. If it
doesn't, there are syntax errors in your metadata file.
* If you have fdroidserver installed:
* Run `fdroid rewritemeta app.id` to clean up your file
* Copy and adjust fdroidserver/examples/config.py to fdroiddata/config.py
* Run `fdroid checkupdates app.id` to fill automated fields like `Auto Name`
and `Current Version`
* Instead of copying a template you can run `fdroid import -u github-url` if
the app is hosted on GitHub
* Make sure that `fdroid lint app.id` doesn't report any warnings. If it does,
fix them.
* Run `fdroid checkupdates app.id`, `fdroid rewritemeta app.id` and `fdroid
build -v -t -l app.id` before opening a merge request!
* Test your build recipe with `fdroid build -v -l app.id`
* Use `git add`, `git commit` and `git push` to update your fork on GitLab.
Please squash multiple commits into a single one per app. It's a good style
to use a separate branch for each app and prefix commit messages with
"Appname:". For this you might also want to look at the `fd-commit` command
in the server repo
Congratulations! You can now open a merge request to add your app.
* Open a merge request via GitLab
Our buildserver runs builds once a day, so it may take up to 24h for your app
to appear in our repository.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment