mirror of
https://gitlab.com/fdroid/fdroidserver.git
synced 2024-07-02 07:20:37 +02:00
Merge branch 'readme-and-contributing' into 'master'
update README and add CONTRIBUTING.md See merge request fdroid/fdroidserver!1353
This commit is contained in:
Hans-Christoph Steiner
commit
44513c23fd
65
CONTRIBUTING.md
Normal file
65
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
There are many ways to contribute, you can find out all the ways on our
|
||||
[Contribute](https://f-droid.org/contribute/) page. Find out how to get
|
||||
involved, including as a translator, data analyst, tester, helping others, and
|
||||
much more!
|
||||
|
||||
## Contributing Code
|
||||
|
||||
We want more contributors and want different points of view represented. Some
|
||||
parts of the code make contributing quick and easy. Other parts make it
|
||||
difficult and slow, so we ask that contributors have patience.
|
||||
|
||||
To submit a patch, please open a merge request on GitLab. If you are thinking of
|
||||
making a large contribution, open an issue or merge request before starting
|
||||
work, to get comments from the community. Someone may be already working on the
|
||||
same thing, or there may be reasons why that feature isn't implemented. Once
|
||||
there is agreement, then the work might need to proceed asynchronously with the
|
||||
core team towards the solution.
|
||||
|
||||
To make it easier to review and accept your merge request, please follow these
|
||||
guidelines:
|
||||
|
||||
* When at all possible, include tests. These can either be added to an existing
|
||||
test, or completely new. Practicing test-driven development will make it
|
||||
easiest to get merged. That usually means starting your work by writing tests.
|
||||
|
||||
* See [help-wanted](https://gitlab.com/fdroid/fdroidserver/-/issues/?sort=updated_desc&state=opened&label_name%5B%5D=help-wanted)
|
||||
tags for things that maintainers have marked as things they want to see
|
||||
merged.
|
||||
|
||||
* The amount of technical debt varies widely in this code base. There are some
|
||||
parts where the code is nicely isolated with good test coverage. There are
|
||||
other parts that are tangled and complicated, full of technical debt, and
|
||||
difficult to test.
|
||||
|
||||
* The general approach is to treat the tangled and complicated parts as an
|
||||
external API (albeit a bad one). That means it needs to stay unchanged as much
|
||||
as possible. Changes to those parts of the code will trigger a migration,
|
||||
which can require a lot of time and coordination. When there is time for large
|
||||
development efforts, we refactor the code to get rid of those areas of
|
||||
technical debt.
|
||||
|
||||
* We use [_black_](https://black.readthedocs.io/) code format, run `black .` to
|
||||
format the code. Whenever editing code in any file, the new code should be
|
||||
formatted as _black_. Some files are not yet fully in _black_ format (see
|
||||
_pyproject.toml_), our goal is to opportunistically convert the code whenever
|
||||
possible. As of the time of this writing, forcing the code format on all files
|
||||
would be too disruptive.
|
||||
|
||||
* Many of the tests run very fast and can be run interactively in isolation.
|
||||
Some of the essential test cases run slowly because they do things like
|
||||
signing files and generating signing keys.
|
||||
|
||||
* Some parts of the code are difficult to test, and currently require a
|
||||
relatively complete production setup in order to effectively test them. That
|
||||
is mostly the code around building packages, managing the disposable VM, and
|
||||
scheduling build jobs to run.
|
||||
|
||||
* For user visible changes (API changes, behaviour changes, etc.), consider
|
||||
adding a note in _CHANGELOG.md_. This could be a summarizing description of
|
||||
the change, and could explain the grander details. Have a look through
|
||||
existing entries for inspiration. Please note that this is NOT simply a copy
|
||||
of git-log one-liners. Also note that security fixes get an entry in
|
||||
_CHANGELOG.md_. This file helps users get more in-depth information of what
|
||||
comes with a specific release without having to sift through the higher noise
|
||||
ratio in git-log.
|
||||
81
README.md
81
README.md
|
|
@ -3,83 +3,84 @@
|
|||
<p><img src="https://gitlab.com/fdroid/artwork/-/raw/master/fdroid-logo-2015/fdroid-logo.svg" width="200"></p>
|
||||
|
||||
# F-Droid Server
|
||||
### Server tools for maintaining an F-Droid repository system.
|
||||
### Tools for maintaining an F-Droid repository system.
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## What is F-Droid?
|
||||
|
||||
F-Droid is an installable catalogue of FOSS (Free and Open Source Software)
|
||||
applications for the Android platform. The client makes it easy to browse,
|
||||
install, and keep track of updates on your device.
|
||||
|
||||
|
||||
## What is F-Droid Server?
|
||||
|
||||
The F-Droid server tools provide various scripts and tools that are
|
||||
used to maintain the main
|
||||
[F-Droid application repository](https://f-droid.org/packages). You
|
||||
can use these same tools to create your own additional or alternative
|
||||
repository for publishing, or to assist in creating, testing and
|
||||
submitting metadata to the main repository.
|
||||
_fdroidserver_ is a suite of tools to publish and work with collections of
|
||||
Android apps (APK files) and other kinds of packages. It is used to maintain
|
||||
the [f-droid.org application repository](https://f-droid.org/packages). These
|
||||
same tools can be used to create additional or alternative repositories for
|
||||
publishing, or to assist in creating, testing and submitting metadata to the
|
||||
f-droid.org repository, also known as
|
||||
[_fdroiddata_](https://gitlab.com/fdroid/fdroiddata).
|
||||
|
||||
For documentation, please see <https://f-droid.org/docs>, or you can
|
||||
find the source for the documentation in
|
||||
[fdroid/fdroid-website](https://gitlab.com/fdroid/fdroid-website).
|
||||
For documentation, please see <https://f-droid.org/docs>.
|
||||
|
||||
In the beginning, _fdroidserver_ was the complete server-side setup that ran
|
||||
f-droid.org. Since then, the website and other parts have been split out into
|
||||
their own projects. The name for this suite of tooling has stayed
|
||||
_fdroidserver_ even though it no longer contains any proper server component.
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
There are many ways to install _fdroidserver_, they are documented on
|
||||
the website:
|
||||
There are many ways to install _fdroidserver_, including using a range of
|
||||
package managers. All of the options are documented on the website:
|
||||
https://f-droid.org/docs/Installing_the_Server_and_Repo_Tools
|
||||
|
||||
All sorts of other documentation lives there as well.
|
||||
|
||||
|
||||
## Tests
|
||||
|
||||
There are many components to all the tests for the components in
|
||||
this git repository. The most commonly used parts of well tested, while
|
||||
some parts still lack tests. This test suite has built over time a
|
||||
bit haphazardly, so it is not as clean, organized, or complete as it
|
||||
could be. We welcome contributions. Before rearchitecting any parts
|
||||
of it, be sure to [contact us](https://f-droid.org/about) to discuss
|
||||
the changes beforehand.
|
||||
To run the full test suite:
|
||||
|
||||
### `fdroid` commands
|
||||
tests/run-tests
|
||||
|
||||
The test suite for all of the `fdroid` commands is in the _tests/_
|
||||
subdir. _.gitlab-ci.yml_ and _.travis.yml_ run this test suite on
|
||||
various configurations.
|
||||
To run the tests for individual Python modules, see the _.TestCase_ files, e.g.:
|
||||
|
||||
tests/metadata.TestCase
|
||||
|
||||
It is also possible to run individual tests:
|
||||
|
||||
tests/metadata.TestCase MetadataTest.test_rewrite_yaml_special_build_params
|
||||
|
||||
There is a growing test suite that has good coverage on a number of key parts of
|
||||
this code base. It does not yet cover all the code, and there are some parts
|
||||
where the technical debt makes it difficult to write unit tests. New tests
|
||||
should be standard Python _unittest_ test cases. Whenever possible, the old
|
||||
tests written in _bash_ in _tests/run-tests_ should be ported to Python.
|
||||
|
||||
This test suite has built over time a bit haphazardly, so it is not as clean,
|
||||
organized, or complete as it could be. We welcome contributions. The goal is
|
||||
to move towards standard Python testing patterns and to expand the unit test
|
||||
coverage. Before rearchitecting any parts of it, be sure to [contact
|
||||
us](https://f-droid.org/about) to discuss the changes beforehand.
|
||||
|
||||
- _tests/run-tests_ runs the whole test suite
|
||||
- _tests/*.TestCase_ are individual unit tests for all of the `fdroid`
|
||||
commands, which can be run separately, e.g. `./update.TestCase`.
|
||||
- run one test: `tests/common.TestCase CommonTest.test_get_apk_id`
|
||||
|
||||
### Additional tests for different linux distributions
|
||||
|
||||
These tests are also run on various distributions through GitLab CI. This is
|
||||
These tests are also run on various configurations through GitLab CI. This is
|
||||
only enabled for `master@fdroid/fdroidserver` because it takes longer to
|
||||
complete than the regular CI tests. Most of the time you won't need to worry
|
||||
about them, but sometimes it might make sense to also run them for your merge
|
||||
request. In that case you need to remove [these lines from
|
||||
.gitlab-ci.yml](https://gitlab.com/fdroid/fdroidserver/blob/master/.gitlab-ci.yml#L34-35)
|
||||
request. In that case you need to remove [these lines from .gitlab-ci.yml](https://gitlab.com/fdroid/fdroidserver/-/blob/0124b9dde99f9cab19c034cbc7d8cc6005a99b48/.gitlab-ci.yml#L90-91)
|
||||
and push this to a new branch of your fork.
|
||||
|
||||
Alternatively [run them
|
||||
locally](https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-exec)
|
||||
like this: `gitlab-runner exec docker ubuntu_lts`
|
||||
|
||||
|
||||
### Buildserver
|
||||
|
||||
The tests for the whole build server setup are entirely separate
|
||||
because they require at least 200 GB of disk space, and 8 GB of
|
||||
RAM. These test scripts are in the root of the project, all starting
|
||||
with _jenkins-_ since they are run on https://jenkins.debian.net.
|
||||
with _jenkins-_ since they used to be run on https://jenkins.debian.net.
|
||||
|
||||
|
||||
## Documentation
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user