1# Contributing to ampache 2 3Ampache is an open source project that loves to receive contributions from our community — you! 4There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, 5submitting bug reports and feature requests or writing code which can be incorporated into Ampache itself. 6 7Anyone can take part in our community and it there are no rules or requirements stopping you from joining. 8Hopefully this document will help you make the jump! 9 10Please read [Development section](https://github.com/ampache/ampache/wiki#development). 11 12## Bug report 13 14Anyone can take part in our community and it there are no rules or requirements stopping you from joining. 15Hopefully this document will help you make the jump! 16 17Be sure the bug is not already fixed in `develop` branch or already reported in current open issues. 18Please add [some logs](https://github.com/ampache/ampache/wiki/Troubleshooting#enable-logging) with your new issue. 19 20## Translations 21 22The official way to send in translations is via [Transifex](https://www.transifex.com/ampache/ampache/dashboard/). 23 24* The official source language of Ampache is US English. 25* Strings should only be translated where they differ from the source language. 26* If a translation is not available, Ampache will fall back to US English. 27 28Ampache uses gettext to handle the translation between different languages. 29If you are interested in translating Ampache into a new language or updating 30an existing translation please join us on Transifex. 31 32Benifits to using the Transifex platform include: 33 34* Everything is managed in a central location. 35* Translations are updated in a single commit without conflicts. 36* The current translation state is available to the team to understand the status of each language. 37 38If you have further questions about translations, please feel free to open an issue and ask for @Psy-Virus - The Translation Guy. 39 40## Bug reports 41 42If you think you have found a bug in Ampache, first make sure that you are testing against the latest [development](https://github.com/ampache/ampache/tree/develop) version. 43Your issue may already have been fixed. If not, search our [issues list](https://github.com/ampache/ampache/issues) on GitHub in case a similar issue has already been opened. 44 45A good tip when searching is to use in:title, in:body or in:comments when searching, especially for specific issues. 46 47* ```warning in:title``` matches issues with "warning" in their title. 48* ```error in:title,body``` matches issues with "error" in their title or body. 49* ```shipit in:comments``` matches issues mentioning "shipit" in their comments. 50 51Check out [docs.github.com](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests) for more info about searching. 52 53It is **very** helpful if you can prepare a reproduction of the bug. We have templates available which will help you when making your report. 54 55* [Bug report](https://raw.githubusercontent.com/ampache/ampache/develop/.github/ISSUE_TEMPLATE/bug_report.md) 56* [Security Policy](https://github.com/ampache/ampache/security/policy) 57 58The easier it is for us to recreate your problem, the faster it is likely to be fixed. 59 60## Feature requests 61 62If you find yourself wishing for a feature that doesn't exist in Ampache, you are probably not alone. 63While Ampache tries to cover as many people as possible there are always going to be features and wants that haven't made it yet. 64 65If you can't find an existing issue, open a new one on the [issues list](https://github.com/ampache/ampache/issues) on GitHub. 66 67Describes the feature you would like to see, why you need it, and how it should work making sure you follow our [Feature request](https://raw.githubusercontent.com/ampache/ampache/develop/.github/ISSUE_TEMPLATE/feature_request.md) template. 68 69## Contributing code and documentation changes 70 71If you would like to contribute a new feature or a bug fix to Ampache, 72please discuss your idea first on the Github issue. If there is no Github issue 73for your idea, please open one. It may be that somebody is already working on 74it, or that there are particular complexities that you should know about before 75starting the implementation. There are often a number of ways to fix a problem 76and it is important to find the right approach before spending time on a PR 77that cannot be merged. 78 79The process for contributing to any of the [Ampache repositories](https://github.com/ampache/) is similar. 80While they are similar, this document is specifically for contributing the the main Ampache repository. 81 82### Fork and clone the repository 83 84You will need to fork the main Ampache code or documentation repository and clone it to your local machine. 85See the [github help page](https://help.github.com/articles/fork-a-repo) for help. 86 87Further instructions for specific projects are given below. 88 89### Tips for code changes 90 91Following these tips prior to raising a pull request will speed up the review cycle. 92 93* Make sure the code you add follows project coding standards and passes all tests before submitting 94* Lines that are not part of your change should not be edited 95 * e.g. don't format unchanged lines, don't reorder existing imports 96* Add the appropriate [license headers](#license-headers) to any new files 97* Make your own branch for your changes based on the develop branch. (e.g. my-patch-branch) 98 99### Coding standards and principles 100 101* We use PSR2 code style 102* We follow the [`SOLID`](https://en.wikipedia.org/wiki/SOLID) principles 103 104### Submitting your changes 105 106Once your changes are ready to submit for review you need to: 107 108#### Test your changes 109 110Run the test scripts to make sure that nothing is broken. 111Please consider adding unit-tests for you newly written code. 112 113```bash 114bash composer qa 115``` 116 117#### Rebase your changes 118 119Update your local repository with the most recent code from the Ampache repository using the latest develop branch. 120 121#### Submit a pull request 122 123Push your local changes to your forked copy of the repository and [submit a pull request](https://help.github.com/articles/using-pull-requests). 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". 124 125Then 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. 126 127The Ampache project love to recognize their contributors and will go to every effort to help make your pull requests meet the standards to merge. 128 129### License Headers 130 131Ampache requires license headers on all PHP files. 132All contributed code should have the following 133license header unless instructed otherwise: 134 135```php 136<?php 137 138declare(strict_types=1); 139 140/** 141 * vim:set softtabstop=4 shiftwidth=4 expandtab: 142 * 143 * LICENSE: GNU Affero General Public License, version 3 (AGPL-3.0-or-later) 144 * Copyright 2001 - 2020 Ampache.org 145 * 146 * This program is free software: you can redistribute it and/or modify 147 * it under the terms of the GNU Affero General Public License as published by 148 * the Free Software Foundation, either version 3 of the License, or 149 * (at your option) any later version. 150 * 151 * This program is distributed in the hope that it will be useful, 152 * but WITHOUT ANY WARRANTY; without even the implied warranty of 153 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 154 * GNU Affero General Public License for more details. 155 * 156 * You should have received a copy of the GNU Affero General Public License 157 * along with this program. If not, see <https://www.gnu.org/licenses/>. 158 * 159 */ 160``` 161 162### Project layout 163 164This repository is split into many top level directories. 165 166#### `bin` 167 168Contains the server CLI applications 169 170#### `config` 171 172Where your Ampache config file resides (ampache.cfg.php) 173 174#### `docs` 175 176Documentation for the project. 177 178#### `locale` 179 180Translations are stored here. 181 182#### `public` 183 184This is the public web root for Amapche and where your webserver should point to. 185 186#### `resources` 187 188Fonts, scripts, templates and non-code resources that are required by Ampache. 189 190#### `src` 191 192Most of the logic resides within the Module folder. The model-files (in `Repository`) may also 193contain application logic, this logic fragments will be migrated into their corresponding domains in `Module` 194 195##### src->Application (deprecated) 196 197Api-related code which didn't fit into existing domains within the Module folder yet. 198 199##### src->Config 200 201Application bootstrapping and config initialization related code. 202 203##### src->Gui (deprecated) 204 205Contains code related to the upcoming templating system. This namespace is deprecated, the code 206will be merged into domains within the Module folder. 207 208##### src->Module 209 210Contains the complete business logic of Ampache, divided into separate domains. 211 212##### src->Plugin 213 214Ampache plugins are placed here. 215 216##### src->Repository 217 218Contains repository classes for database access as well as the ORM model classes. 219 220#### `tests` 221 222Tests for Ampache using phpunit. The folder structure mirrors the structures within `src`. 223 224#### `vendor` 225 226Third-Party composer requirements that are not maintained by Ampache. 227 228## Reviewing and accepting your contribution 229 230We review every contribution carefully to ensure that the change is of high 231quality and fits well with the rest of the Ampache codebase. ourselves. 232 233We really appreciate everyone who is interested in contributing to 234Ampache and regret that we sometimes have to reject contributions even 235when they might appear to make genuine improvements to the system. 236 237Please discuss your change in a Github issue before spending much time on its 238implementation. We sometimes have to reject contributions that duplicate other 239efforts, take the wrong approach to solving a problem, or solve a problem which 240does not need solving. An up-front discussion often saves a good deal of wasted 241time in these cases. 242 243We expect you to follow up on review comments somewhat promptly, but recognise 244that everyone has many priorities for their time and may not be able to respond 245for several days. We will understand if you find yourself without the time to 246complete your contribution, but please let us know that you have stopped 247working on it. We may close your PR if you do not respond for too long. 248 249If your contribution is rejected we will close the pull request with a comment 250explaining why. if you feel we have misunderstood your intended change 251or otherwise think that we should reconsider then please continue the conversation 252and we'll do our best to address any further points you raise. 253