User guide

General contributor guidelines

    Helping on the forum

    You are more than welcome to help on the forum by answering questions of users. Please remember that English is the forum language so most people have a chance to understand.

    If we see you helping a lot you may even be provided with moderator status and so to speak be part of the "support team".

    Reporting bugs

    Zenphoto is constantly developed and sometimes new bugs sneak in without being noticed while fixing other things. By testing the development version from GitHub you help finding these.

    Some guidelines to help us to help you in reporting bugs:

    1. Disable all third party plugins and theme and try to reproduce the issue with an official theme. Our ability to diagnose problems is much aided if we can reproduce them ourselves.
    2. Always use the latest Zenphoto release. We can provide only minimal support for versions that are not current. If you are experiencing problems you should first upgrade your site to the current version of Zenphoto.
    3. Try the support build from GitHub to see if your issue perhaps has already been fixed in development.

    If the above does not already resolve your issue, please follow these further steps:

    1. Open a new topic on the forum (you need to register first) or if you are sure it is a bug even better a ticket on GitHub (You need to create a free GitHub account).
    2. Please one issue/topic per ticket and use a descriptive ticket name. Please don't mix several or even unrelated issues in one ticket. For general questions please use the forum
    3. Provide a detailed description of your problem with step-by-step directions to reproduce the problem
    4. Provide detailed information like:
      • Zenphoto version
      • Theme used
      • Plugins used
      • Server configuration
      • Browser and which version/system
    5. Review the your error logs. If you get blank pages this is the first you should do. Ask your host if you don't know where the server logs are located:
      • Zenphoto debug log (please set the Zenphoto language to the default English so we understand it!)
      • Server (php) error log
      • Browser error log
    6. Also please state what browser and which version you are using and report any error shown in your browser error log.
    7. Post links to your site if it is public. Posting screen captures limits the information we can get as we often need to look at the underlying HTML to see what is going on.
    8. In case an image file or the like is involved post a link to the file so we can try to reproduce.
    9. Please monitor your forum topic or ticket regulary as we probably will have follow up questions and your answers will help us to fix an possible issue faster. If you don't respond and we cannot reproduce your issue at all, tickets may be closed unsolved after maximum two weeks.

    Here is a diagram to visualize the process:

    bugreport-guidelines

    Providing bug fixes and patches

    You can also provide bug fixes or patches via GitHub using pull requests. You need a free GitHub account to do so. We may or may not choose to include after reviewing them. Please only include one pull request per issue/fix/feature whatever at the time so it is possible to conveniently review them.

    Be sure to use the latest Zenphoto release or even better the current support release.

    Note: By providing pull request you agree to release them under the GPL v2 or later license Zenphoto is released under if they are included. If your code includes parts by third parties make sure you note them and best review if their parts are compatible.

    Submitting feature additions

    We welcome any contribution. You can offer them via pull requests mentioned above. But best first create a "feature request" ticket to suggest and discuss it or discuss it on the forum. We generally recommend to try new features as a plugin. We like to keep the core project as slim as possible.
    Please understand that we may choose to not incorporate your changes or ideas.

    If you made a plugin we encourage you to make it available for the community. Just let us know and we add it to our site listing. Please see below for more detailed info on submitting 3rd party plugins.

    Security issue reports

    Security issues should obviously not be made public until a fix is available. Please use our contact page to contact us.

    Providing translations

    Zenphoto is used internationally and although we have a regular team of translators a lot of languages are of course still missing. You can submit your translation for inclusion in the release package or decide to selfhost it. Before starting an translation please read our translating tutorial that has detailed info how Zenphoto's translation works and what tools you need to provide a translation.

    Note: By submitting a translation you agree that it may be distributed with the Zenphoto download package. Your translation should be provided under a open license compatible to Zenphoto's GPL v2 or later license. If no special license note is attached, we will assume GPL v2 or later.

    Contributing to documentations or write tutorials

    We try hard to document everything Zenphoto related but there may be things missing. You can suggest things on the forum. If your tutorial is good to go we may move it to the real user guide section or provide a link.

    Note: Our documentation is released under a Creative Commons Attribution Share Alike license. By submitting anything for inclusion you agree to this license.

    If you have written on your blog or found something useful elsewhere let us know via the forum, too. We then either add a link to your site and/or post it on our news sections.

    Feature suggestions

    If you have an idea for a feature, you can discuss this on the forum or better please open a ticket on the GitHub issue tracker (You need a free account there).

    But please note: Opening a ticket will be considered as a suggestion and the developers can't guarantee if and when it will be done.

    Of course if you or anyone else wants to code it yourself as a 3rd party solution, this is very welcome, too. You can discuss everything on the forum of course.

    Providing themes and plugins

    We can't do everything ourselves especially specific requirements. Therefore we welcome any third party theme or plugin. Of course it is assumed that you have some knowledge of general web techniques and have read specifically theming tutorial, developer coding guidelines and other related articles on our user guide section.

    1. Be sure to use the most recent Zenphoto release.Best is to also test the current support build to be safe for the next release, too..
    2. Provide a readme file and list if your theme or plugin requires anything specific like server configuration. Also if your theme supports specific plugins or requires special settings to run as expected.
    3. Your plugin or theme should work standalone and should not be calling any parts from third party servers. You should not load scripts, fonts or anything else from any external source like cdn's. If you really, really must do this, please state explicitly in your theme or plugin documentation. Best would be to provide an option to disable it and use local files only. The exception are of course plugins for services like Twitter, Facebook or the like where this might be problematic to avoid.
    4. If you took over or modified an existing theme that has been abandoned beware of its licence. While the code may be under a GPL open source license, the design may not and released under a specific license (like the stopdesign themes that are not free for commercial use!)
    5. For plugins only: Third party plugins must be setup to work from the root plugins folder. 
    6. Create a page for the plugin or theme on your website that we can link to from our themes or extensions section. We generally don't host third party themes or plugins as we have no resources to maintain them (except for some very old ones for archive purposes) and we don't do direct download links to avoid confusion. A project page on code hosting services like Google Code, GitHub or the like is of course fine.
    7. Let us know on the forum or via our social channels Twitter, Google+ and Facebook what you did so we can add it to the related sections. Also let us know about updates. We gladly post about them on our channels.
    8. You may also use the Zenphoto forum to provide free support for your theme or plugin unless you offer paid support (please see below).
    Licences

    Plugins and their code as well as the PHP code of your theme will most likely be GPL v2 or later like Zenphoto as well since the GPL licenses demands that derived code must be distributed under the same terms. It must not be GPL v2 or later but a compatible licence.

    However individual parts of the code or the overall design may very well be protected under another license. You may choose any licence or usage condition you wish for your theme's design. The Creative Commons licenses variants are very suitable for this.

    If your theme or plugin uses 3rd party tools that are not GPL v2 or later compatible or do not allow for example commercial use please state this explicitly. You agree that we use text excerpts for the entry from your site/page and/or in case of a theme screenshots to create an entry on our site and on our social network channels.

    Credits on modifyied or adapted themes and plugins

    Following the section "licences" please give a proper credit if your theme or plugin is based on someone else's work. Many themes have a credit in the footer and the theme_description.php file. We would recommend something like "Theme design by X based on theme Y by Z". Preferably linked. Although not mandatory best leave the "Powered by Zenphoto" line. Alternatively if your site has an imprint that is a good place instead of a footer as well. 

    For plugins the proper credit to the plugin description and the main doc comment block at the beginning.

    These are general rules so of course a theme or plugin author may have different condiditions. Always look at the licences used.

    Selling plugins/themes and/or support

    Since Zenphoto themes (code) and plugins being derivative must be licenced GPL v2 or later or with a compatible licence, those licences do allow selling the themes/plugins or the support for them. However, it is not the same selling as proprietary software or "hardware" goods. See here for some info:
    http://www.gnu.org/licenses/gpl-faq.en.html#DoesTheGPLAllowMoney

    We will list commercial themes and plugins on our appropiate sections and will note they are not free. Please understand that our forum cannot be used for commercial, paid support.

    Creative Commons LicenseThis text by www.zenphoto.org is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

    For questions and comments please use the forum or discuss on the social networks.

    Related items