mirror of
https://gitlab.com/fdroid/fdroidserver.git
synced 2024-10-03 17:50:11 +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:
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>
|
<p><img src="https://gitlab.com/fdroid/artwork/-/raw/master/fdroid-logo-2015/fdroid-logo.svg" width="200"></p>
|
||||||
|
|
||||||
# F-Droid Server
|
# F-Droid Server
|
||||||
### Server tools for maintaining an F-Droid repository system.
|
### Tools for maintaining an F-Droid repository system.
|
||||||
|
|
||||||
</div>
|
</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?
|
## What is F-Droid Server?
|
||||||
|
|
||||||
The F-Droid server tools provide various scripts and tools that are
|
_fdroidserver_ is a suite of tools to publish and work with collections of
|
||||||
used to maintain the main
|
Android apps (APK files) and other kinds of packages. It is used to maintain
|
||||||
[F-Droid application repository](https://f-droid.org/packages). You
|
the [f-droid.org application repository](https://f-droid.org/packages). These
|
||||||
can use these same tools to create your own additional or alternative
|
same tools can be used to create additional or alternative repositories for
|
||||||
repository for publishing, or to assist in creating, testing and
|
publishing, or to assist in creating, testing and submitting metadata to the
|
||||||
submitting metadata to the main repository.
|
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
|
For documentation, please see <https://f-droid.org/docs>.
|
||||||
find the source for the documentation in
|
|
||||||
[fdroid/fdroid-website](https://gitlab.com/fdroid/fdroid-website).
|
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
|
## Installing
|
||||||
|
|
||||||
There are many ways to install _fdroidserver_, they are documented on
|
There are many ways to install _fdroidserver_, including using a range of
|
||||||
the website:
|
package managers. All of the options are documented on the website:
|
||||||
https://f-droid.org/docs/Installing_the_Server_and_Repo_Tools
|
https://f-droid.org/docs/Installing_the_Server_and_Repo_Tools
|
||||||
|
|
||||||
All sorts of other documentation lives there as well.
|
|
||||||
|
|
||||||
|
|
||||||
## Tests
|
## Tests
|
||||||
|
|
||||||
There are many components to all the tests for the components in
|
To run the full test suite:
|
||||||
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.
|
|
||||||
|
|
||||||
### `fdroid` commands
|
tests/run-tests
|
||||||
|
|
||||||
The test suite for all of the `fdroid` commands is in the _tests/_
|
To run the tests for individual Python modules, see the _.TestCase_ files, e.g.:
|
||||||
subdir. _.gitlab-ci.yml_ and _.travis.yml_ run this test suite on
|
|
||||||
various configurations.
|
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
|
### 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
|
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
|
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
|
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
|
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)
|
||||||
.gitlab-ci.yml](https://gitlab.com/fdroid/fdroidserver/blob/master/.gitlab-ci.yml#L34-35)
|
|
||||||
and push this to a new branch of your fork.
|
and push this to a new branch of your fork.
|
||||||
|
|
||||||
Alternatively [run them
|
Alternatively [run them
|
||||||
locally](https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-exec)
|
locally](https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-exec)
|
||||||
like this: `gitlab-runner exec docker ubuntu_lts`
|
like this: `gitlab-runner exec docker ubuntu_lts`
|
||||||
|
|
||||||
|
|
||||||
### Buildserver
|
### Buildserver
|
||||||
|
|
||||||
The tests for the whole build server setup are entirely separate
|
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
|
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
|
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
|
## Documentation
|
||||||
|
Loading…
Reference in New Issue
Block a user