Merge branch 'stable'

docs/README.md

@@ -21,3 +21,9 @@ Having trouble? We’d like to help!
 
 - [:question: Try the Forum – it’s got answers to many common questions](https://discourse.libretime.org/).
 - [:bug: Report bugs with LibreTime in our ticket tracker.](https://github.com/libretime/libretime/issues)
+
+## History
+
+LibreTime is a fork of AirTime due to stalled development of the open source version. For background on this, see this [open letter to the Airtime community](https://gist.github.com/hairmare/8c03b69c9accc90cfe31fd7e77c3b07d).
+
+Airtime itself was based on the software called Campcaster. You can find more information about the [early days of Campcaster and Airtime in the repository](https://github.com/libretime/libretime/blob/main/LEGACY.md).

docs/admin-manual/backup.md

@@ -27,17 +27,17 @@ On common setups, you need to backup the entire `/etc/libretime` folder.
 
 You need to backup the PostgreSQL database, which holds the entire data of your installation.
 
-Here is an example to dump your PostgreSQL database:
+Here is an example to dump your PostgreSQL database to a plain text SQL file:
 
 ```bash
-sudo -u postgres pg_dump --file=libretime.sql libretime
+sudo -u postgres pg_dump --no-owner --no-privileges libretime > libretime.sql
 ```
 
 :::note
 
-Consider using the `--no-owner` and `--no-privileges` flags to ignore roles
+We use the `--no-owner` and `--no-privileges` flags to ignore roles
 and permissions details about the database. This can be useful when restoring
-to database or role that have different names.
+to database or role that have different names (e.g. `airtime` to `libretime`).
 
 :::
 
@@ -65,15 +65,25 @@ If you are upgrading LibreTime, edit the configuration file to match the new con
 
 ### Restore the database
 
-Restore the database by using the following command:
+Restore the database by using the one of the following command depending on the format of you backup file:
 
 ```bash
-sudo -u postgres pg_restore --dbname=libretime libretime.sql
+# With a plain text SQL file
+sudo -u libretime libretime-api dbshell < libretime.sql
+
+# With a custom pg_dump format
+sudo -u postgres pg_restore --no-owner --no-privileges --dbname=libretime libretime.dump
 ```
 
+:::info
+
+The `libretime-api dbshell` command is a shortcut to the `psql` command, and automatically passes the database access details (e.g. database name, user, password).
+
+:::
+
 :::note
 
-Consider using the `--no-owner` and `--no-privileges` flags to ignore roles
+We use the `--no-owner` and `--no-privileges` flags to ignore roles
 and permissions details about the database. This can be useful when restoring
 to database or role that have different names.
 

docs/admin-manual/setup/install.md

@@ -46,7 +46,7 @@ LibreTime requires the following default ports to be open:
 
 The installer is shipped in the released tarballs or directly in the project repository.
 
-We recommend installing on one of the following [distribution releases](../../developer-manual/development/releases.md#distributions-releases-support):
+We recommend installing on one of the following [distribution releases](../../contributor-manual/releases.md#distributions-releases-support):
 
 - [Debian 11](https://www.debian.org/releases/)
 - [Ubuntu 20.04 LTS](https://wiki.ubuntu.com/Releases)

docs/admin-manual/setup/upgrade.md

@@ -11,6 +11,12 @@ You should always have proper backups and a rollback scenario in place before up
 
 :::
 
+:::info
+
+You may upgrade LibreTime by migrating to a new server. This is probably the cleanest way if you are coming from [Airtime](./migrate-from-airtime.md), if you wish to upgrade the underlying system, or if you want to skip multiple upgrade procedures.
+
+:::
+
 ## Stop the services
 
 Run the following commands to stop the services:
@@ -33,6 +39,12 @@ Follow [the backup guide](../backup.md) to make an extra backup of your installa
 
 Be sure to carefully read **all** the [releases notes](../../releases/README.md), from your current version to the targeted version, to apply upgrade or breaking changes instructions to your installation.
 
+:::danger
+
+If you are migrating LibreTime to a new server, you must **not** apply the upgrade procedure.
+
+:::
+
 :::caution
 
 You might need to run steps before and after the install procedure. Be sure to follow these steps thoroughly.
@@ -43,6 +55,12 @@ You might need to run steps before and after the install procedure. Be sure to f
 
 Follow [the install guide](./install.md#download) to download and install the new version, and re-run the `./install` script with the same arguments you used during the initial install.
 
+:::caution
+
+If you are migrating LibreTime to a new server, you must **stop before the [setup tasks](./install.md#setup)** and [restore the backups](../backup.md#restore-a-backup) on the new server.
+
+:::
+
 ## Apply migrations
 
 Run the following command to apply the database migrations:

docs/contribute.md

@@ -0,0 +1,48 @@
+# Contributing to LibreTime
+
+First and foremost, thank you! We appreciate that you want to contribute to
+LibreTime, your time is valuable, and your contributions mean a lot to us.
+
+Before any contribution, read and be prepared to adhere to our
+[code of conduct](https://github.com/libretime/organization/blob/main/CODE_OF_CONDUCT.md).
+
+LibreTime development workflows follow the standardized [C4 development process](https://rfc.zeromq.org/spec:42/c4/), with some LibreTime specific changes:
+
+- [2.3. Patch Requirements](https://rfc.zeromq.org/spec/42/#23-patch-requirements)
+  - 7. A patch commit message MUST follow the [conventional commits specification](https://www.conventionalcommits.org/en/v1.0.0/).
+- [2.4. Development Process](https://rfc.zeromq.org/spec/42/#24-development-process)
+  - 16. Maintainers MAY NOT merge incorrect patches.
+
+## Contribute financially
+
+LibreTime is run by volunteers who manage the project in their spare time. Financial contributions help us pay for our domain and infrastructure. It can also be used to cover the costs of development for important features and conference attendance. If you wish to contribute financially, you can do so through our [OpenCollective](https://opencollective.com/libretime).
+
+## Write documentation
+
+One of the simplest ways to get started contributing to a project is through improving documentation. LibreTime is constantly evolving, this means that sometimes our documentation has gaps. You can help by adding missing sections, editing the existing content so it is more accessible or creating new content (tutorials, FAQs, etc).
+
+Issues pertaining to the documentation are usually marked with the [documentation](https://github.com/libretime/libretime/issues?q=is%3Aopen+is%3Aissue+label%3A%22is%3A+documentation%22) label.
+
+## Translate LibreTime
+
+LibreTime can run in over 15 different languages due to the gracious help of our volunteers.
+
+LibreTime is localized using [Weblate](https://weblate.org/). If you would like to contribute a language translation, create an account and start working on [our Weblate page](https://hosted.weblate.org/projects/libretime/).
+
+## Report bugs or request features
+
+Help us improve LibreTime by [submitting a bug report or suggesting new features](https://github.com/libretime/libretime/issues). When you are creating a report, please include as many details as possible.
+
+You will find more details on how to submit a report on the [issue creation page](https://github.com/libretime/libretime/issues/new/choose).
+
+The [official issue tracker](https://github.com/libretime/libretime/issues) is hosted on Github.
+
+## Contribute with code
+
+Are you familiar with coding in PHP or Python? Have you made projects in [Liquidsoap](https://www.liquidsoap.info/) and some of the other services we use? Help us improve LibreTime by picking an issue in the [list of bugs and feature requests](https://github.com/libretime/libretime/issues).
+
+Then [fork our repo](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) and [setup a development environment](https://libretime.org/docs/contributor-manual/development-environment.md) to get you started! Make sure to setup [pre-commit](https://libretime.org/docs/contributor-manual/development-workflows.md#pre-commit) to enforce the project best practices before committing new code.
+
+Knowledge on how to use [Github](https://guides.github.com/activities/hello-world/)
+and [Git](https://git-scm.com/docs/gittutorial) will suit you well, use the
+links for a quick 101.

docs/contributor-manual/README.md

@@ -0,0 +1,11 @@
+---
+title: Contributor manual
+---
+
+Welcome to the **LibreTime contributor manual**, you should find guides to improve and contribute to LibreTime.
+
+- Learn about the [architecture of LibreTime](./design/architecture.md)
+- Learn about the [database design](./design/database.md)
+
+- Learn about the [development workflows of LibreTime](./development-workflows.md)
+- Start coding by setting up a [development environment](./development-environment.md)

docs/contributor-manual/_category_.yml

@@ -0,0 +1,2 @@
+label: Contributor manual
+position: 50

docs/contributor-manual/design/database.md

@@ -1,4 +1,10 @@
-# Database schema creation and migrations
+---
+title: Database
+---
+
+LibreTime is designed to work with a [PostgreSQL](https://www.postgresql.org/) database server and uses both the [PropelORM](https://github.com/propelorm/Propel) in the legacy app and [Django ORM](https://docs.djangoproject.com/en/4.1/topics/db/models/) in the API to interact with the database.
+
+## Database schema creation and migrations
 
 The method to maintain the database schema, is to write both a migration file for already installed databases and to update a `schema.sql` file for fresh databases. On fresh installation, the database is filled with the `schema.sql` and `data.sql` files and LibreTime won't run any sql migration on top of it. Previously, when LibreTime was upgraded, the missing migrations were run using a custom php based migration tool, those migrations are now handled by Django. The missing migrations are tracked using both a `schema_version` field in the `cc_pref` table and a Django migration id.
 
@@ -49,3 +55,13 @@ stateDiagram-v2
 
     apply_django_migration --> [*]
 ```
+
+## Modifying the database schema
+
+To modify the database schema use the following steps:
+
+1. Modify `legacy/build/schema.xml`.
+2. Run `make -C legacy propel-gen` to regenerate the legacy files.
+3. Run `pre-commit run --all` and `make -C legacy format` multiple times to clean and format the previously generated files.
+4. Update the `api` models to reflect the changes made to the schema.
+5. Create a new schema migration file in the `api/legacy/migrations` directory.

docs/contributor-manual/development-environment.md

@@ -2,6 +2,10 @@
 title: Development environment
 ---
 
+This page describes the different way to run LibreTime in a development environment.
+
+The recommended development environment is the [docker-compose setup](#docker-compose).
+
 ## Docker-compose
 
 To setup a docker-compose development environment, run the following commands:
@@ -21,6 +25,18 @@ docker-compose up -d
 docker-compose logs -f
 ```
 
+:::info
+
+You may also use the following `make clean dev` shortcut:
+
+```bash
+make clean dev
+
+docker-compose logs -f
+```
+
+:::
+
 ## Vagrant
 
 To use Vagrant, you need to install a virtualization engine: [VirtualBox](https://www.virtualbox.org) or Libvirt. The [vagrant-vbguest] package on Github can help maintain guest extensions on host systems using VirtualBox.
@@ -128,7 +144,7 @@ multipass shell ltTEST
 ```
 
 Multipass isn't currently able to do an automated install from the cloud-init script.
-After you enter the shell for the first time, you will still need to [run the LibreTime installer](../../admin-manual/setup/install.md).
+After you enter the shell for the first time, you will still need to [run the LibreTime installer](../admin-manual/setup/install.md).
 
 The IP address of your new VM can be found by running `multipass list`. Copy and paste it into your web browser to access the LibreTime interface and complete the setup wizard.
 

docs/contributor-manual/development-workflows.md

@@ -0,0 +1,77 @@
+---
+title: Development workflows
+---
+
+## Git workflow
+
+LibreTime uses [Github pull requests to manage changes](https://docs.github.com/en/get-started/quickstart/contributing-to-projects). The workflow looks like this:
+
+- [Create a fork of the project](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
+- Check out the `main` branch. If you're making a minor or small documentation change you can check out the `stable` branch.
+- Create a new branch based on the checked out branch.
+- Work on your changes locally. Try to keep each commit small to make reviews easier.
+- Lint and test the codebase, for example using the `make lint` or `make test` commands inside the app folder you want to check.
+- Push your branch.
+- Create a pull request in Github.
+- We'll review your request and provide feed back.
+
+## Project layout
+
+The LibreTime repository is split into multiple tools/services/apps at the root of the project. You will find `Makefile` in each of the component of the project. Those `Makefile` describe the different commands available to develop the project.
+
+Here is a small description of the different components in the repository:
+
+```bash
+.
+├── analyzer      # The LibreTime Analyzer service
+├── api           # The LibreTime API service
+├── api-client    # The API clients used internally by other services
+├── docker        # The docker related files
+├── docs          # The documentation
+├── install       # The install script
+├── installer     # The install script extra files
+├── legacy        # The LibreTime Legacy service
+├── playout       # The LibreTime Playout service
+├── shared        # A shared library using by our python based services
+├── tools         # Set of tools used to maintain the project
+├── website       # Website repository that is cloned when developing the documentation
+└── worker        # The LibreTime Worker service
+```
+
+For example, to lint and test the `analyzer` service, you can run the commands:
+
+```bash
+make -C analyzer lint test
+
+# Or by changing into the analyzer directory
+cd analyzer
+make lint test
+```
+
+## Pre-commit
+
+LibreTime uses [pre-commit](https://pre-commit.com/) to ensure that the files you commit are properly formatted, follow best practice, and don’t contain syntax or spelling errors.
+
+You can install and setup pre-commit using the [quick-start guide on the pre-commit documentation](https://pre-commit.com/#quick-start). Make sure to install pre-commit and setup the git pre-commit hook so pre-commit runs before you commit any changes to the repository.
+
+The workflow looks like this:
+
+- Install pre-commit.
+- After cloning the repository, setup the pre-commit git hooks:
+
+  ```bash
+  pre-commit install
+  ```
+
+- Make your changes and commit them.
+- If pre-commit fails to validate your changes, the commit process stops. Fix any reported errors and try again.
+
+:::info
+
+You can also run pre-commit anytime on all the files using:
+
+```bash
+pre-commit run --all-files
+```
+
+:::

docs/developer-manual/README.md

@@ -2,13 +2,8 @@
 title: Developer manual
 ---
 
-Welcome to the **LibreTime developer manual**, you should find guides to integrate LibreTime and tools to improve and contribute to LibreTime.
+Welcome to the **LibreTime developer manual**, you should find guides to integrate LibreTime.
 
 ## Integrate LibreTime
 
 - :construction: Work in progress
-
-## Improve and contribute to LibreTime
-
-- Learn about the [architecture of LibreTime](./design/architecture.md)
-- Learn about the [database migrations](./design/database-migrations.md)

docs/developer-manual/development/_category_.yml

@@ -1 +0,0 @@
-label: Development

docs/releases/3.0.0-beta.0.md

@@ -109,7 +109,7 @@ The LibreTime project wants to thank the following contributors for authoring PR
 
 ### Ubuntu Bionic support deprecation
 
-Support for Ubuntu Bionic is being deprecated, and will be removed in LibreTime v3.1.0. Maintenance only versions (3.0.x) for Ubuntu Bionic will be provided until the distribution release reaches its end of life. Please see the [supported distributions release policy](../developer-manual/development/releases.md#distributions-releases-support) for details.
+Support for Ubuntu Bionic is being deprecated, and will be removed in LibreTime v3.1.0. Maintenance only versions (3.0.x) for Ubuntu Bionic will be provided until the distribution release reaches its end of life. Please see the [supported distributions release policy](../contributor-manual/releases.md#distributions-releases-support) for details.
 
 Along with the Ubuntu Bionic deprecation, the following dependencies versions are also being deprecated:
 
@@ -119,7 +119,7 @@ Along with the Ubuntu Bionic deprecation, the following dependencies versions ar
 
 ### Debian Buster support deprecation
 
-Support for Debian Buster is being deprecated, and will be removed in LibreTime v3.1.0. Maintenance only versions (3.0.x) for Debian Buster will be provided until the distribution release reaches its end of life. Please see the [supported distributions release policy](../developer-manual/development/releases.md#distributions-releases-support) for details.
+Support for Debian Buster is being deprecated, and will be removed in LibreTime v3.1.0. Maintenance only versions (3.0.x) for Debian Buster will be provided until the distribution release reaches its end of life. Please see the [supported distributions release policy](../contributor-manual/releases.md#distributions-releases-support) for details.
 
 Along with the Debian Buster deprecation, the following dependencies versions are also being deprecated:
 

docs/releases/3.0.0.md

@@ -31,4 +31,4 @@ AAC streams aren't working out of the box because the [current distributions pac
 
 ### On Ubuntu Bionic, analyzing some FLAC files fails
 
-[On Ubuntu Bionic, analyzing some FLAC files fails with `UnplayableFileError`](https://github.com/libretime/libretime/issues/2218) because of an upstream bug in Liquidsoap. If you encounter this, you should [upgrade to a more recent distribution version](../developer-manual/development/releases.md#distributions-releases-support).
+[On Ubuntu Bionic, analyzing some FLAC files fails with `UnplayableFileError`](https://github.com/libretime/libretime/issues/2218) because of an upstream bug in Liquidsoap. If you encounter this, you should [upgrade to a more recent distribution version](../contributor-manual/releases.md#distributions-releases-support).