Merge pull request #1227 from jooola/update_contibuting
Improve CONTRIBUTING and community links
This commit is contained in:
Kyle Robbertze
GitHub
commit
16a9168d4f
|
|
@ -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.
|
||||||
133
CONTRIBUTING.md
133
CONTRIBUTING.md
|
|
@ -1,43 +1,91 @@
|
||||||
# Contributing to LibreTime
|
# Contributing to LibreTime
|
||||||
|
|
||||||
First and foremost, thank you! We appreciate that you want to
|
First and foremost, thank you! We appreciate that you want to contribute to
|
||||||
contribute to LibreTime, your time is valuable, and your
|
LibreTime, your time is valuable, and your contributions mean a lot to us.
|
||||||
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
|
In addition, LibreTime follow the standardized
|
||||||
project. But there are many ways to contribute, including
|
[C4 development process](https://rfc.zeromq.org/spec:42/c4/), in which you can
|
||||||
the following:
|
find explanation about most of the development workflows for LibreTime.
|
||||||
|
|
||||||
- Updating or correcting documentation
|
**How to contribute**
|
||||||
- Feature requests
|
|
||||||
- Bug reports
|
|
||||||
|
|
||||||
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)
|
## Reporting bugs
|
||||||
- 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
|
|
||||||
|
|
||||||
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?
|
Before creating bug reports, please check the following list, to be sure that
|
||||||
- **distro**: what distribution is your install on and which distro version are you using (ie. Ubuntu Trusty)
|
you need to create one:
|
||||||
- **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
|
|
||||||
|
|
||||||
Please wrap all code and error messages in [markdown code
|
- **Check the [LibreTime forum](https://discourse.libretime.org/)** for existing
|
||||||
fences](https://help.github.com/articles/creating-and-highlighting-code-blocks/).
|
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
|
When you are creating a bug report, please include as many details as possible.
|
||||||
install a [`pre-commit`](https://pre-commit.com/) hook that will check that everything is in order:
|
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
|
```bash
|
||||||
|
sudo apt install pre-commit
|
||||||
pre-commit install
|
pre-commit install
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -46,3 +94,36 @@ You can also run it anytime using:
|
||||||
```bash
|
```bash
|
||||||
pre-commit run --all-files
|
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).
|
||||||
|
|
|
||||||
|
|
@ -1,67 +1,97 @@
|
||||||
---
|
---
|
||||||
title: Contribute to Libretime
|
title: Contribute to LibreTime
|
||||||
layout: article
|
layout: article
|
||||||
category: dev
|
category: dev
|
||||||
permalink: /contribute
|
permalink: /contribute
|
||||||
---
|
---
|
||||||
|
|
||||||
> LibreTime is a fork of AirTime due to stalled development of the open source version. For background on this,
|
> LibreTime is a fork of AirTime due to stalled development of the open source
|
||||||
> see this [open letter to the Airtime community](https://gist.github.com/hairmare/8c03b69c9accc90cfe31fd7e77c3b07d).
|
> 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
|
## 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).
|
Following these guidelines helps maintainers and the community understand your
|
||||||
Create a bug report by selecting **Get Started** next to **Bug Report**. That way, the LibreTime team can keep track of
|
report, reproduce the behavior, and find related reports.
|
||||||
your problem and notify you when it has been fixed. You can also suggest
|
|
||||||
improvements and new features for LibreTime on that site.
|
|
||||||
|
|
||||||
## 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
|
- **Check the [LibreTime forum](https://discourse.libretime.org/)** for existing
|
||||||
[Github issues page](https://github.com/LibreTime/libretime/issues/new/choose).
|
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
|
## Translation
|
||||||
|
|
||||||
LibreTime can run in over 15 different languages due to the gracious help of our volunteers. Is your language not
|
LibreTime can run in over 15 different languages due to the gracious help of our
|
||||||
supported? Follow [this guide](/docs/interface-localization) to add your language to LibreTime!
|
volunteers. Is your language not supported? Follow [this guide](/docs/interface-localization)
|
||||||
|
to add your language to LibreTime!
|
||||||
|
|
||||||
## Write documentation
|
## 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.
|
One of the simplest ways to get started contributing to a project is through
|
||||||
After cloning our repo locally, enter the `docs/` directory and run
|
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
|
bundle install
|
||||||
jekyll serve
|
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;`
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue