2
0
mirror of https://github.com/janeczku/calibre-web synced 2024-10-31 15:20:28 +00:00
calibre-web/CONTRIBUTING.md
2020-04-25 08:55:01 +02:00

4.9 KiB

How to contribute to Calibre-Web

First of all, I would like to thank you for reading this text. I'm happy you are willing to contribute to Calibre-Web

General

Communication language is english. Google translated texts are not as bad as you might think, they are usually understandable, so don't worry if you generate your post that way.

Calibre-Web is not Calibre. If you are having a question regarding Calibre please post this at their repository.

Docker-Containers of Calibre-Web are maintained by different persons than the people who drive Calibre-Web. If we come to the conclusion during our analysis that the problem is related to Docker, we might ask you to open a new issue at the reprository of the Docker Container.

If you are having Basic Installation Problems with python or it's dependencies, please consider using your favorite search engine to find a solution. In case you can't find a solution, we are happy to help you.

We can offer only very limited support regarding configuration of Reverse-Proxy Installations, OPDS-Reader or other programs in combination with Calibre-Web.

Translation

Some of the user languages in Calibre-Web having missing translations. We are happy to add the missing texts if you are translate them. Create a Pull Request, create an issue with the .po file attached, or write an email to "ozzie.fernandez.isaacs@googlemail.com" with attached translation file. To display all book languages in your native language an additional file is used (iso_language_names.py). The content of this file is autogenerated with the corresponding translations of Calibre, please do not edit this file on your own.

Documentation

The Calibre-Web documentation is hosted in the Github Wiki. The Wiki is open to everybody, if you find a problem, feel free to correct it. If information is missing, you are welcome to add it. The content will be reviewed time by time. Please try to be consitent with the form with the other Wiki pages (e.g. the project name is Calibre-Web with 2 capital letters and a dash in between).

Reporting a bug

Do not open up a GitHub issue if the bug is a security vulnerability in Calibre-Web. Please write intead an email to "ozzie.fernandez.isaacs@googlemail.com".

Ensure the *bug was not already reported by searching on GitHub under Issues. Please also check if a solution for your problem can be found in the wiki.

If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, the issue form helps you providing the right information. Deleting the form and just pasting the stack trace doesn't speed up fixing the problem. If your issue could be resolved, consider closing the issue.

Feature Request

If there is afeature missing in Calibre-Web and you can't find a feature request in the Issues section, you could create a feature request. We will not extend Calibre-Web with any more login abilitys or add further files storages, or file syncing ability. Furthermore Calibre-Web is made for home usage for company inhouse usage, so requests regarding any sorts of social interaction capability, payment routines, search engine or web site analytics integration will not be implemeted.

Contributing code to Calibre-Web

Open a new GitHub pull request with the patch. Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.

In case your code enhances features of Calibre-Web: Create your pull request for the development branch if your enhancement consits of more than some lines of code in a local section of Calibre-Webs code. This makes it easier to test it and check all implication before it's made public.

Please check if your code runs on Python 2.7 (still necessary in 2020) and mainly on python 3. If possible and the feature is related to operating system functions, try to check it on Windows and Linux. Calibre-Web is automatically tested on Linux in combination with python 3.7. The code for testing is in a seperate repo on Github. It uses unittest and performs real system tests with selenium, would be great if you could consider also writing some tests. A static code analysis is done by Codacy, but it's partly broken and doesn't run automatically. You could check your code with ESLint before contributing, a configuration file can be found in the projects root folder.