Ampache is an open source project that loves to receive contributions from our community — you! There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into Ampache itself.
Anyone can take part in our community and it there are no rules or requirements stopping you from joining. Hopefully this document will help you make the jump!
Please read Development section.
Anyone can take part in our community and it there are no rules or requirements stopping you from joining. Hopefully this document will help you make the jump!
Be sure the bug is not already fixed in develop branch or already reported in current open issues.
Please add some logs with your new issue.
The official way to send in translations is via Transifex.
- The official source language of Ampache is US English.
- Strings should only be translated where they differ from the source language.
- If a translation is not available, Ampache will fall back to US English.
Ampache uses gettext to handle the translation between different languages. If you are interested in translating Ampache into a new language or updating an existing translation please join us on Transifex.
Benifits to using the Transifex platform include:
- Everything is managed in a central location.
- Translations are updated in a single commit without conflicts.
- The current translation state is available to the team to understand the status of each language.
If you have further questions about translations, please feel free to open an issue and ask for @Psy-Virus - The Translation Guy.
If you think you have found a bug in Ampache, first make sure that you are testing against the latest development version. Your issue may already have been fixed. If not, search our issues list on GitHub in case a similar issue has already been opened.
A good tip when searching is to use in:title, in:body or in:comments when searching, especially for specific issues.
warning in:titlematches issues with "warning" in their title.error in:title,bodymatches issues with "error" in their title or body.shipit in:commentsmatches issues mentioning "shipit" in their comments.
Check out docs.github.com for more info about searching.
It is very helpful if you can prepare a reproduction of the bug. We have templates available which will help you when making your report.
The easier it is for us to recreate your problem, the faster it is likely to be fixed.
If you find yourself wishing for a feature that doesn't exist in Ampache, you are probably not alone. While Ampache tries to cover as many people as possible there are always going to be features and wants that haven't made it yet.
If you can't find an existing issue, open a new one on the issues list on GitHub.
Describes the feature you would like to see, why you need it, and how it should work making sure you follow our Feature request template.
If you would like to contribute a new feature or a bug fix to Ampache, please discuss your idea first on the Github issue. If there is no Github issue for your idea, please open one. It may be that somebody is already working on it, or that there are particular complexities that you should know about before starting the implementation. There are often a number of ways to fix a problem and it is important to find the right approach before spending time on a PR that cannot be merged.
The process for contributing to any of the Ampache repositories is similar. While they are similar, this document is specifically for contributing the the main Ampache repository.
You will need to fork the main Ampache code or documentation repository and clone it to your local machine. See the github help page for help.
Further instructions for specific projects are given below.
Following these tips prior to raising a pull request will speed up the review cycle.
- Make sure the code you add follows project coding standards and passes all tests before submitting
- Lines that are not part of your change should not be edited
- e.g. don't format unchanged lines, don't reorder existing imports
- Add the appropriate license headers to any new files
- Make your own branch for your changes based on the develop branch. (e.g. my-patch-branch)
- We use PSR2 code style
- We follow the
SOLIDprinciples
Once your changes are ready to submit for review you need to:
Run the test scripts to make sure that nothing is broken. Please consider adding unit-tests for you newly written code.
bash composer qaUpdate your local repository with the most recent code from the Ampache repository using the latest develop branch.
Push your local changes to your forked copy of the repository and submit a pull request. In the pull request, choose a title which sums up the changes that you have made, and in the body provide more details about what your changes do. Also mention the number of the issue where discussion has taken place, eg "Closes #123".
Then sit back and wait. There will probably be discussion about the pull request and, if any changes are needed, we would love to work with you to get your pull request merged into Ampache.
The Ampache project love to recognize their contributors and will go to every effort to help make your pull requests meet the standards to merge.
Ampache requires license headers on all PHP files. All contributed code should have the following license header unless instructed otherwise:
<?php
declare(strict_types=1);
/**
* vim:set softtabstop=4 shiftwidth=4 expandtab:
*
* LICENSE: GNU Affero General Public License, version 3 (AGPL-3.0-or-later)
* Copyright Ampache.org, 2001-2023
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
*/This repository is split into many top level directories.
Contains the server CLI applications
Where your Ampache config file resides (ampache.cfg.php)
Documentation for the project.
Translations are stored here.
This is the public web root for Amapche and where your webserver should point to.
Fonts, scripts, templates and non-code resources that are required by Ampache.
Most of the logic resides within the Module folder. The model-files (in Repository) may also
contain application logic, this logic fragments will be migrated into their corresponding domains in Module
Api-related code which didn't fit into existing domains within the Module folder yet.
Application bootstrapping and config initialization related code.
Contains code related to the upcoming templating system. This namespace is deprecated, the code will be merged into domains within the Module folder.
Contains the complete business logic of Ampache, divided into separate domains.
Ampache plugins are placed here.
Contains repository classes for database access as well as the ORM model classes.
Tests for Ampache using phpunit. The folder structure mirrors the structures within src.
Third-Party composer requirements that are not maintained by Ampache.
We review every contribution carefully to ensure that the change is of high quality and fits well with the rest of the Ampache codebase. ourselves.
We really appreciate everyone who is interested in contributing to Ampache and regret that we sometimes have to reject contributions even when they might appear to make genuine improvements to the system.
Please discuss your change in a Github issue before spending much time on its implementation. We sometimes have to reject contributions that duplicate other efforts, take the wrong approach to solving a problem, or solve a problem which does not need solving. An up-front discussion often saves a good deal of wasted time in these cases.
We expect you to follow up on review comments somewhat promptly, but recognise that everyone has many priorities for their time and may not be able to respond for several days. We will understand if you find yourself without the time to complete your contribution, but please let us know that you have stopped working on it. We may close your PR if you do not respond for too long.
If your contribution is rejected we will close the pull request with a comment explaining why. if you feel we have misunderstood your intended change or otherwise think that we should reconsider then please continue the conversation and we'll do our best to address any further points you raise.