History: DevTips
Comparing version 78 with version 101
|
|||
| Lines: 2-14 | Lines: 2-14 | ||
| These tips are here to help new contributors getting a feel for the environment. Some people are inclined to follow these as "Rules" or "Guidelines"; they are suggestions rather than strict requirements. Consider each point below as information about what is in Tiki. As a contributing coder, you should respect that environment. You may wish to read everything below in detail. | These tips are here to help new contributors getting a feel for the environment. Some people are inclined to follow these as "Rules" or "Guidelines"; they are suggestions rather than strict requirements. Consider each point below as information about what is in Tiki. As a contributing coder, you should respect that environment. You may wish to read everything below in detail. | ||
| - | !!If you only read one line |
+ | !! If you only read one line __(aka TL;DR)__ |
| * __((3 Rules))__ : 1/ __Respect Environment__ 2/ __Commit Early, Commit Often__ 3/ __Make it Optional__ | * __((3 Rules))__ : 1/ __Respect Environment__ 2/ __Commit Early, Commit Often__ 3/ __Make it Optional__ | ||
| - | !!Commits *(( *((Commit Code |
+ | !! Commits *((Git Workflow|How to commit)) |
| *((Where to commit)) | *((Where to commit)) | ||
| - | !!File names conventions and generalities | + | !! File names conventions and generalities |
| * All __file names are lowercase__ | * All __file names are lowercase__ | ||
| ** Only exceptions are 3rd party libs like Zend framework and other libs requiring "PSR-0 standard for PHP class naming allowing for autoload" | ** Only exceptions are 3rd party libs like Zend framework and other libs requiring "PSR-0 standard for PHP class naming allowing for autoload" | ||
| Lines: 20-50 | Lines: 20-49 | ||
| * Avoid names like feature_new, feature_newer, feature_newest... | * Avoid names like feature_new, feature_newer, feature_newest... | ||
| - | !!Files content integrity * __Never change * Prefer to use only * Be careful with your text editor. Make sure that it uses __LF__ [http://www-test.lib.umn.edu/webteam/docs/tutorials/unix-line-endings.html|Unix line endings] and not CRLF Windows line endings. __Only exception__ perhaps are Smarty templates in -+templates/mail/+- used for sending mails which should use CRLF because some Windows servers seem to have problem with sending mails then (see [http:// |
+ | !! Files content integrity * __Never change indentation on code you don't change__. It could provoke diff and merge inconsistencies * Prefer to use only __tabs for indentation__ for a new file * Be careful with your text editor. Make sure that it uses __LF__ [http://www-test.lib.umn.edu/webteam/docs/tutorials/unix-line-endings.html|Unix line endings] and not CRLF Windows line endings. __Only exception__ perhaps are Smarty templates in -+templates/mail/+- used for sending mails which should use CRLF because some Windows servers seem to have a problem with sending mails then (see [http://tiki.org/tiki-view_forum_thread.php?forumId=6&comments_parentId=32076&thread_sort_mode=commentDate_asc|this thread|external]). If in doubt, use the end of line character from the file that you changed. |
| * Use only __UTF-8__ encoding for language files. Hence, use a UTF-8-enabled text editor for those files. | * Use only __UTF-8__ encoding for language files. Hence, use a UTF-8-enabled text editor for those files. | ||
| - | !!Strings integrity | + | !! Strings integrity |
| * Follow the format convention: ((Strings Format Convention)) | * Follow the format convention: ((Strings Format Convention)) | ||
| * Reuse the same terminology | * Reuse the same terminology | ||
| + | * Descriptions (like preferences descriptions) should end with a "." In general, any sentence should end with the complete punctuation. | ||
| - | !! * !!!Commit messages |
+ | !! Git operations * See ((Where to commit) !!! Commit messages |
| Take in mind that your commit message should be clear and describe all operations that this commit is for. Feel free to give the tracker ticket that this commit is closing (if it is the case). | Take in mind that your commit message should be clear and describe all operations that this commit is for. Feel free to give the tracker ticket that this commit is closing (if it is the case). | ||
| - | Your commit message {include page="Commit Tags" } The canonical list of tags is in |
+ | Your commit message may start with one or more of the tags listed at the top of [https://sourceforge.net/p/tikiwiki/code/HEAD/tree/trunk/changelog.txt|changelog.txt] to distinguish changes. |
| If you are doing a ((Backport)) to an earlier branch of a commit in trunk, see also this page: ((Merge a commit from trunk)) | If you are doing a ((Backport)) to an earlier branch of a commit in trunk, see also this page: ((Merge a commit from trunk)) | ||
| - | !!Database conventions | + | !! Database conventions |
| * All table names begin with ~~#446688:tiki_ except users_~~ for historical reasons | * All table names begin with ~~#446688:tiki_ except users_~~ for historical reasons | ||
| * __Table name has to be less than 26 characters__, all lowercase, using chars and underscores | * __Table name has to be less than 26 characters__, all lowercase, using chars and underscores | ||
| * Primary keys in tables usually use the following convention : objectId with a capital 'I'. It's a rare case where a capital is used in any name | * Primary keys in tables usually use the following convention : objectId with a capital 'I'. It's a rare case where a capital is used in any name | ||
| - | * When you modify the schema (create / modify tables), you need to care for both future installs and existing installs (upgrades). For future installs, you need to modify ''db/tiki.sql'' |
+ | * When you modify the schema (create / modify tables), you need to care for both future installs and existing installs (upgrades). For future installs, you need to modify ''db/tiki.sql''. See ((Database Schema Upgrade)) for more information |
| * Respect abstraction scheme and naming conventions for queries as detailed on ((tw:DbAbstractionDev)) | * Respect abstraction scheme and naming conventions for queries as detailed on ((tw:DbAbstractionDev)) | ||
| * __Do not use reserved words__ for column name (for instance __do not use: user, status, order, show for column name__) | * __Do not use reserved words__ for column name (for instance __do not use: user, status, order, show for column name__) | ||
| Lines: 54-131 | Lines: 53-115 | ||
| !! PHP coding habits | !! PHP coding habits | ||
| - | * Coding standards: please use [https://framework.zend.com/manual/2.4/en/ref/coding.standard.html|Zend Framework Coding Standard]~tc~Could not find version for Zend Framework 3. Chealer 2017-01-05~/tc~ *** Indentation using tabs rather than spaces |
+ | !!! Tiki 23 and up https://www.php-fig.org/psr/psr-12 !!!- Tiki 22. and before * Coding standards: please use [https://framework.zend.com/manual/2.4/en/ref/coding.standard.html|Zend Framework Coding Standard]~tc~Could not find the version for Zend Framework 3. Chealer 2017-01-05~/tc~ your code. * Exceptions: *** __WE USE TABS__ - Indentation using tabs rather than spaces |
| **The Zend coding standard was adopted after Tiki had accumulated a significant PHP code base which did not follow this standard. Tiki's current PHP code is still far from adhering to this standard everywhere, in particular when it comes to function names, which were previously written completely lowercase, with underscores between words. For example, as of 2017-01-22, we have clean_logs() , which should be named "cleanLogs" according to our standards. Some old sets of functions called dynamically even require to be named fully lowercase. For example, the FOO plugin requires a function named "wikiplugin_foo" as of 2017-01-22. | **The Zend coding standard was adopted after Tiki had accumulated a significant PHP code base which did not follow this standard. Tiki's current PHP code is still far from adhering to this standard everywhere, in particular when it comes to function names, which were previously written completely lowercase, with underscores between words. For example, as of 2017-01-22, we have clean_logs() , which should be named "cleanLogs" according to our standards. Some old sets of functions called dynamically even require to be named fully lowercase. For example, the FOO plugin requires a function named "wikiplugin_foo" as of 2017-01-22. | ||
| - | * Do not end a php file with > ! PHP version issues |
+ | * All the strings are written to be easily translated using the ''tr()'' function. E.g. -+tr('some string')+- |
| + | !! PHP Security Guidelines | ||
| + | All commits will be reviewed for security issues. It's a good idea to familiarize yourself with the expectations of Tiki commits outlined on the ((Secure Coding Practice Guidelines)) page. | ||
| !! Files should start with... | !! Files should start with... | ||
| {CODE(caption="1st line of Smarty templates (.tpl)", colors=smarty)} | {CODE(caption="1st line of Smarty templates (.tpl)", colors=smarty)} | ||
| - | {* $Id$ *} | ||
| {CODE} | {CODE} | ||
| - | {CODE(caption="Start of PHP files (.php)" wrap="1" colors="php")} // (c) Copyright |
+ | {CODE(caption="Start of PHP files (.php)" wrap="1" colors="php" theme="default")}<?php // (c) Copyright by authors of the Tiki Wiki/CMS/Groupware Project |
| // | // | ||
| // All Rights Reserved. See copyright.txt for details and a complete list of authors. | // All Rights Reserved. See copyright.txt for details and a complete list of authors. | ||
| // Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See license.txt for details. | // Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See license.txt for details. | ||
| - | // $Id$ | ||
| {CODE} | {CODE} | ||
| - | {CODE svn propset svn php {CODE} |
+ | !! Front-end Tiki serves __HTML__ (version 5) documents. The [http://validator.w3.org|W3C Markup Validator] can help checking the validity of your design, but is experimental. |
| - | svn commit filename. { } !! coding suggestions * ''. * |
+ | Since Tiki versions prior to 9 used XHTML, several void elements are written with needless trailing slashes (for example, "<img />", instead of "~np~<img>~/np~") . For the following tags you can (or should ?) use the shorter notation: * br, img, link, param, meta, input, area, base, br, col, command, and embed ( following [http://www.w3.org/TR/html-markup/syntax.html#void-elements|"void elements"] ) |
| - | * For Tiki releases lesser than Tiki 9.x HTML code is __XHTML 1.0 Transitional__ compatible. Use the [http://validator.w3.org] * Since Tiki 9.x : ** br, img, link, param, meta, input, area, base, br, col, command, and embed ) * In other words it means usage of the shorter <img> instead of <img />, etc. See discussion on ((Mass operations to do after the Semi-automatic merging period |
+ | CSS stylesheets are widely used to __separate design from content__ and to create ((Themes)). |
| - | + | !!! Smarty templates * Strings displayed are enclosed by ''~np~{tr}{/tr}~/np~'' blocks for translation * There are no standards about Smarty template formatting (either from Tiki or Smarty). However, templates shipped by Smarty and Smarty documentation appear to use template indentation rather than output indentation (in other words, the indentation facilitates reading the template rather than reading the generated HTML), as can be seen in [https://www.smarty.net/docs/en/language.function.call.tpl|Smarty's "Calling a recursive menu example" . * Comments in Smarty code can be useful. The Smarty comment delimiter is ''{* *}''. | |
| - | + | !! Introduction to Tiki Code | |
| ((Introduction to Tiki Code Layout)) | ((Introduction to Tiki Code Layout)) | ||
| - | !!Best Practices *((Bootstrap) *((Templates Best Practices ) *((Filtering Best |
+ | !! Best Practices * ((Bootstrap) * ((Templates Best Practices ) * ((Filtering Best Practices)) |
| - | !!Icons | + | !! Icons |
| * See ((icons)) if you want to use icons in the templates | * See ((icons)) if you want to use icons in the templates | ||
| - | !!Think of ReleaseProcess * Mention your meaningful changes * |
+ | !! Think of ReleaseProcess * Mention your meaningful changes on a TikiXY page (where XY is main Tiki version number, e.g. Tiki17) on https://doc.tiki.org. It is useful for users to know what is new or changed in the upcoming Tiki version (we do not output the commit messages to changelog.txt file anymore since Tiki 16.2). |
| - | !!About license * Code needs to have __LGPL__, |
+ | !! About license * Code needs to have __LGPL__, MIT or BSD-like licenses if bundled in Tiki (not GPL). Please see ((tw:LibLicense)) |
| - | + | --External GPL code, like [http://wollabot.sourceforge.net/|Wollabot], is an exception.-- | |
| - | !!Setting up a debugger/development environment The following links may be useful reference: |
+ | !! Setting up a debugger/development environment The following links may be a useful reference: |
| ((Xdebug etc)) | ((Xdebug etc)) | ||
| Lines: 135-147 | Lines: 119-129 | ||
| ---- | ---- | ||
| - | + | See also, on t.o, in progress of migration here : | |
| * ((3 Rules)) | * ((3 Rules)) | ||
| - | + some basic |
+ | + some basic principles about contribution in Tiki development community |
| * ((tw:GuidelinesDev)) | * ((tw:GuidelinesDev)) | ||
| + old page before this one, still holds good information | + old page before this one, still holds good information | ||
| * ((tw:DbAbstractionDev)) | * ((tw:DbAbstractionDev)) | ||
| + a little messy but very helpful page to know how to write your sql queries in libraries. | + a little messy but very helpful page to know how to write your sql queries in libraries. | ||
| - | * ((tw:CvsEtiquette)) | ||
| - | + the current CVS common practices. | ||
| * ((tw:TikiDevelopment)) | * ((tw:TikiDevelopment)) | ||
| + Useful links to development tools and material. | + Useful links to development tools and material. | ||
| Lines: 152-164 | Lines: 134-145 | ||
| * ((Strings Format Convention)) | * ((Strings Format Convention)) | ||
| + String format convention | + String format convention | ||
| - | * ((Hello World|a tutorial for |
+ | * ((Hello World|a tutorial for developer beginners)) |
| * ((Permission Revamp)) explains how the permissions work | * ((Permission Revamp)) explains how the permissions work | ||
| - | !!Code Maps and Howtos |
+ | !! Code Maps and Howtos |
| Because Tiki is a large system, it can sometimes be hard to find your way around the code, or how to accomplish a specific task like "adding a new icon". The ((Code Maps and Howtos)) page contains links to: | Because Tiki is a large system, it can sometimes be hard to find your way around the code, or how to accomplish a specific task like "adding a new icon". The ((Code Maps and Howtos)) page contains links to: | ||
| - | * Code "maps" that can help you orient yourself and navigate a particular part of the code (ex: the |
+ | * Code "maps" that can help you orient yourself and navigate a particular part of the code (ex: the multilingual functionalities of Tiki). |
| * Code "howtos" that can help you figure out how to carry out a specific programming task, for example, "adding a new icon" to the UI. | * Code "howtos" that can help you figure out how to carry out a specific programming task, for example, "adding a new icon" to the UI. | ||
| - | All coders are |
+ | All coders are encouraged to write such maps to help others. If you are a newbie to a particular part of the code or particular kind of task and find that they are not covered, you might want to create a map or how to keep track of your findings and document what you find so others will benefit from it in the future. |
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}