General contributor guidelines November 29, 2009 / Updated: June 13, 2022

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 7 days.

Here is a diagram to visualize the process:

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).

Note: Opening a ticket will be considered as a suggestion and the developers can't guarantee if and when it will be done. Please understand that a feature might be important to you but not necessarily to us. Sadly we need to be picky what we work on as we don't have unlimited time and resource.

If possible please investigate and consider to create it as 3rd party plugin for example. This is very welcome. 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 general knowledge of web techniques and have read specifically theming tutorial, developer coding guidelines and other related articles on our user guide section. Please  follow these recommendations as we otherwise might not add your theme or plugin to the extensions section.

1. Be sure to use the most recent Zenphoto release.Best is to also test the current support build (beta) 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.
   1. Note if your plugin/theme supports specific plugins or has  requirements
   2. For plugins: Define $plugin_disable of your plugin with the required conditions.
   3. For themes: Define  $theme_description['disable' ] of your theme with the require conditions.
   4. The theme or plugin must be explicitly compatible with Zenphoto.
3. Your plugin or theme should work standalone and should not be calling any parts from third party servers. 
   1. You should not load scripts, fonts or anything else from any external source like a cdn. If you really, really must do this, please state explicitly in your theme or plugin documentation.
   2. Best would be to provide an option to disable it and use local files only. Leave the choice to the user.
   3. The exception are of course plugins for services like Twitter, Facebook or the like where this might be problematic to avoid external source.
   4. For plugins: Define $plugin_notice if you use external sources.
   5. For themes: Define $theme_description['notice' ]  if you use external sources.
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 specific page for the plugin or theme
   
   1. This must be a sub page of your website with infos, documentation and updates of your plugin or theme. A repository on code hosting services like GitHub is also fine.
   2. 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.
   3. The theme or plugin must be separately available for download and not be bundled within any other project.
7. Let us know on the forum or via our social channels Twitter 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.

• https://en.wikipedia.org/wiki/GNU_General_Public_License
• https://www.gnu.org/licenses/gpl.html
• https://www.gnu.org/licenses/license-list.en.html#GPLCompatibleLicenses

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:
https://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.