diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..294e7f3e7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,9 @@ +blank_issues_enabled: false +contact_links: + - name: LibreTime Forum + url: https://discourse.libretime.org/ + about: Please find existing questions and discussions here. + + - name: LibreTime Chat + url: https://chat.libretime.org/ + about: Discuss with the LibreTime community. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a2aa8da7..a17b59ec5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,43 +1,91 @@ # 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. +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. -**What does "contributing" mean?** +Before any contribution, read and be prepared to adhere to our +[code of conduct](https://github.com/libretime/code-of-conduct/blob/master/code_of_conduct.md). -Creating an issue is the simplest form of contributing to a -project. But there are many ways to contribute, including -the following: +In addition, LibreTime follow the standardized +[C4 development process](https://rfc.zeromq.org/spec:42/c4/), in which you can +find explanation about most of the development workflows for LibreTime. -- Updating or correcting documentation -- Feature requests -- Bug reports +**How to contribute** -Before opening an issue, please: +- [Reporting bugs](#reporting-bugs) +- [Suggesting enhancements](#suggesting-enhancements) +- [Financially](https://libretime.org/contribute#financial) +- [Contributing to documentation](https://libretime.org/contribute#write-documentation) +- [Contributing to code](#code) -- read and be prepared to adhere to our [code of conduct](https://github.com/LibreTime/code-of-conduct/blob/master/CODE_OF_CONDUCT.md) -- understand that we follow the standardized [C4 development process](https://rfc.zeromq.org/spec:42/C4/) -- [search for existing duplicate or closed issues](https://github.com/LibreTime/libretime/issues?utf8=%E2%9C%93&q=is%3Aissue) -- clearly state the problem you would like to solve in a meaningful way -- be prepared to follow up on issues by providing additional information as requested by a maintainer or contributor helping you out +## Reporting bugs -For bug reports, please provide the following details: +This section guides you through submitting a bug report for LibreTime. +Following these guidelines helps maintainers and the community understand your +report, reproduce the behavior, and find related reports. -- **version**: what version of LibreTime you were using when you experienced the bug? -- **distro**: what distribution is your install on and which distro version are you using (ie. Ubuntu Trusty) -- **reduced test case**: the minimum amount of detail needed to reproduce the bug -- **error messages**: please paste any error reports into the issue or a gist +Before creating bug reports, please check the following list, to be sure that +you need to create one: -Please wrap all code and error messages in [markdown code -fences](https://help.github.com/articles/creating-and-highlighting-code-blocks/). +- **Check the [LibreTime forum](https://discourse.libretime.org/)** for existing + questions and discussion. +- **Check that your issue does not already exist in the + [issue tracker](https://github.com/libretime/libretime/issues?q=is%3aissue+label%3abug)**. -### Contributing code +> **Note:** If you find a **Closed** issue that seems like it is the same thing +> that you're experiencing, open a new issue and include a link to the original +> issue in the body of your new one. -To make sure that you don't accidentally commit code that does not follow the coding style, you can -install a [`pre-commit`](https://pre-commit.com/) hook that will check that everything is in order: +When you are creating a bug report, please include as many details as possible. +Fill out the [required template](https://github.com/libretime/libretime/issues/new?labels=bug&template=bug_report.md), +the information it asks helps the maintainers resolve the issue faster. + +Bugs are tracked on the [official issue tracker](https://github.com/libretime/libretime/issues). + +## Suggesting enhancements + +This section guides you through submitting an enhancement suggestion for +LibreTime, including completely new features and minor improvements to existing +functionality. Following these guidelines helps maintainers and the community +understand your suggestion and find related suggestions. + +Before creating enhancement suggestions, please check the following list, as you +might find out that you don't need to create one: + +- **Check the [LibreTime forum](https://discourse.libretime.org/)** for existing + questions and discussion. +- **Check that your issue does not already exist in the + [issue tracker](https://github.com/libretime/libretime/issues?q=is%3aissue+label%3afeature-request)**. + +When you are creating an enhancement suggestion, please include as many details +as possible. Fill in [the template](https://github.com/libretime/libretime/issues/new?labels=feature-request&template=feature_request.md), +including the steps that you imagine you would take if the feature you're +requesting existed. + +## Code + +Are you familiar with coding in PHP or Python? Have you made projects in +Liquidsoap and some of the other services we use? Take a look at the +[list of bugs and feature requests](https://github.com/LibreTime/libretime/issues), +and then fork our repo and have a go! Just use the **Fork** button at the top of +our [GitHub page](https://github.com/LibreTime/libretime), clone the forked repo +to your desktop, open up a favorite editor and make some changes, and then +commit, push, and open a pull request. + +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. + +LibreTime uses the [black](https://github.com/psf/black) coding style for Python +and you must ensure that your code follows it. If not, the CI will fail and your +Pull Request will not be merged. Similarly, the Python import statements are +sorted with [isort](https://github.com/pycqa/isort). There is configuration +provided for [pre-commit](https://pre-commit.com/), which will ensure that code +matches the expected style and conventions when you commit changes. It is set up +by running: ```bash +sudo apt install pre-commit pre-commit install ``` @@ -46,3 +94,36 @@ You can also run it anytime using: ```bash pre-commit run --all-files ``` + +## Testing and CI/CD + +Before submitting code to the project, it's a good idea to test it first. To do +this, it's easiest to install LibreTime in a virtual machine on your local +system or in a cloud VM. We have instructions for setting up a virtual instance +of LibreTime with [Vagrant](/docs/vagrant) and [Multipass](/docs/multipass). + +If you would like to try LibreTime in a Docker image, Odclive has instructions +[here](https://github.com/kessibi/libretime-docker) for setting up a test image +and a more persistent install. + +## Modifying the Database + +LibreTime is designed to work with a [PostgreSQL](https://www.postgresql.org/) +database server running locally. LibreTime uses [PropelORM](http://propelorm.org) +to interact with the ZendPHP components and create the database. The version 2 +API uses Django to interact with the same database. + +If you are a developer seeking to add new columns to the database here are the steps. + +1. Modify `airtime_mvc/build/schema.xml` with any changes. +2. Run `dev_tools/propel_generate.sh` +3. Update the upgrade.sql under `airtime_mvc/application/controllers/upgrade_sql/VERSION` for example + `ALTER TABLE imported_podcast ADD COLUMN album_override boolean default 'f' NOT NULL;` +4. Update the models under `api/libretimeapi/models/` to reflect the new + changes. + +## Documentation and financial contributions + +More information about how to contribute documentation or financially +through our [OpenCollective](https://opencollective.com/libretime) can be found +on our [website](https://libretime.org/contribute). diff --git a/docs/_docs/contribute.md b/docs/_docs/contribute.md index 9fcd9127c..7aa3d07c6 100644 --- a/docs/_docs/contribute.md +++ b/docs/_docs/contribute.md @@ -1,67 +1,97 @@ --- -title: Contribute to Libretime +title: Contribute to LibreTime layout: article category: dev permalink: /contribute --- -> 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). +> 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). + +## Code of conduct + +Before any contribution, read and be prepared to adhere to our +[code of conduct](https://github.com/libretime/code-of-conduct/blob/master/code_of_conduct.md). + +In addition, LibreTime follow the standardized +[C4 development process](https://rfc.zeromq.org/spec:42/c4/), in which you can +find explanation about most of the development workflows for LibreTime. ## Bug reporting -If you think you've found a bug, please report it on our [Github issues page](https://github.com/LibreTime/libretime/issues/new/choose). -Create a bug report by selecting **Get Started** next to **Bug Report**. That way, the LibreTime team can keep track of -your problem and notify you when it has been fixed. You can also suggest -improvements and new features for LibreTime on that site. +Following these guidelines helps maintainers and the community understand your +report, reproduce the behavior, and find related reports. -## Feature requests +Before creating bug reports, please check the following list, to be sure that +you need to create one: -Have an idea that would make Libretime even better than it is right now? Start a **Feature request** on our -[Github issues page](https://github.com/LibreTime/libretime/issues/new/choose). +- **Check the [LibreTime forum](https://discourse.libretime.org/)** for existing + questions and discussion. +- **Check that your issue does not already exist in the + [issue tracker](https://github.com/libretime/libretime/issues?q=is%3aissue+label%3abug)**. + +> **Note:** If you find a **Closed** issue that seems like it is the same thing +> that you're experiencing, open a new issue and include a link to the original +> issue in the body of your new one. + +When you are creating a bug report, please include as many details as possible. +Fill out the [required template](https://github.com/libretime/libretime/issues/new?labels=bug&template=bug_report.md), +the information it asks helps the maintainers resolve the issue faster. + +Bugs are tracked on the [official issue tracker](https://github.com/libretime/libretime/issues). + +## Suggesting enhancements + +This section guides you through submitting an enhancement suggestion for +LibreTime, including completely new features and minor improvements to existing +functionality. Following these guidelines helps maintainers and the community +understand your suggestion and find related suggestions. + +Before creating enhancement suggestions, please check the following list, as you +might find out that you don't need to create one: + +- **Check the [LibreTime forum](https://discourse.libretime.org/)** for existing + questions and discussion. +- **Check that your issue does not already exist in the + [issue tracker](https://github.com/libretime/libretime/issues?q=is%3aissue+label%3afeature-request)**. + +When you are creating an enhancement suggestion, please include as many details +as possible. Fill in [the template](https://github.com/libretime/libretime/issues/new?labels=feature-request&template=feature_request.md), +including the steps that you imagine you would take if the feature you're +requesting existed. + +## Financial + +LibreTime is run by volunteers who write code and manage the project in their +spare time. Financial contributions help us pay for our domain and back-end +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). ## Translation -LibreTime can run in over 15 different languages due to the gracious help of our volunteers. Is your language not -supported? Follow [this guide](/docs/interface-localization) to add your language to LibreTime! +LibreTime can run in over 15 different languages due to the gracious help of our +volunteers. Is your language not supported? Follow [this guide](/docs/interface-localization) +to add your language to LibreTime! ## Write documentation -Our site is now built by Jekyll, which has an installation guide [here](https://jekyllrb.com/docs/installation/) to help get you started. -After cloning our repo locally, enter the `docs/` directory and run +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/labels/documentation) +label. + +Our site is built by Jekyll, which has an installation guide [here](https://jekyllrb.com/docs/installation/) +to help get you started. After cloning our repo locally, enter the `docs/` +directory and run ``` bundle install jekyll serve ``` - -## Code - -Are you familiar with coding in PHP? Have you made projects in Liquidsoap and some of the other services we use? -Take a look at the [list of bugs and feature requests](https://github.com/LibreTime/libretime/issues), and then -fork our repo and have a go! Just use the **Fork** button at the top of our **Code** page, clone the forked repo to -your desktop, open up a favorite editor and make some changes, and then commit, push, and open a pull request. -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. - -## Testing and CI/CD - -Before submitting code to the project, it's a good idea to test it first. To do this, it's easiest to install -LibreTime in a virtual machine on your local system or in a cloud VM. We have instructions for setting up a virtual -instance of LibreTime with [Vagrant](/docs/vagrant) and [Multipass](/docs/multipass). - -If you would like to try LibreTime in a Docker image, -Odclive has instructions [here](https://github.com/kessibi/libretime-docker) for setting up a test image -and a more persistent install. - -## Modifying the Database - -LibreTime is designed to work with a [PostgreSQL](https://www.postgresql.org/) database server running locally. -LibreTime uses [PropelORM](http://propelorm.org) to interact with the ZendPHP components and create the database. - -If you are a developer seeking to add new columns to the database here are the steps. - -1. Modify `airtime_mvc/build/schema.xml` with any changes. -2. Run `dev_tools/propel_generate.sh` -3. Update the upgrade.sql under `airtime_mvc/application/controllers/upgrade_sql/VERSION` for example - `ALTER TABLE imported_podcast ADD COLUMN album_override boolean default 'f' NOT NULL;`