khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-03 18:26:42 +07:00
Code Issues Packages Projects Releases Wiki Activity

Restructure the dev manual

Browse Source 
This moves lots of pages around. The high-level changes are

* Better main sections, so it's more *general*, *into*, *basics* and *details*
* Move more general topics to a *Basic* section, which are not
  app-specific
* Remove app docs to the stuff that is likely used, anything else goes
  into "Digging deeper"
* Move general guides into a prologue
* Try to *compress*/combine some pages with similar content
* Try to have better consistencs on level ob abstraction across pages
* Split app development and maintenance pages into two sections
* Integrate bugtracker info into prologue
* Integrate Android pages into client APIs section

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
This commit is contained in:
Christoph Wurst
2020-06-22 18:35:59 +02:00
parent 547810edd8
commit 2647cd93c7
71 changed files with 228 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

467
developer_manual/getting_started/codingguidelines.rst Normal file
View File

@@ -0,0 +1,467 @@
=================================
Coding style & general guidelines
=================================
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
General
-------
* Ideally, discuss your plans on the `forums <https://help.nextcloud.com>`_ to see if others want to work with you on it
* We use `GitHub <https://github.com/nextcloud>`_, please get an account there and clone the repositories you want to work on
* Fixes go directly to master, nevertheless they need to be tested thoroughly.
* New features are always developed in a branch and only merged to master once they are fully done.
* Software should work. We only put features into master when they are complete. It's better to not have a feature instead of having one that works poorly.
* It is best to start working based on an issue - create one if there is none. You describe what you want to do, ask feedback on the direction you take it and take it from there.
* When you are finished, use the merge request function on GitHub to create a pull request. The other developers will look at it and give you feedback. You can signify that your PR is ready for review by adding the label "5 - ready for review" to it. You can also post your merge request to the mailing list to let people know. See `the code review page for more information <../bugtracker/codereviews.html>`_
* It is key to keep changes separate and small. The bigger and more hairy a PR grows, the harder it is to get it in. So split things up where you can in smaller changes - if you need a small improvement like a API addition for a big feature addition, get it in first rather than adding it to the big piece of work!
* Decisions are made by consensus. We strive for making the best technical decisions and as nobody can know everything, we collaborate. That means a first negative comment might not be the final word, neither is positive feedback an immediate GO. Nextcloud is built out of modular pieces (apps) and maintainers have a strong influence. In case of disagreement we consult other seasoned contributors.
Labels
------
We assign labels to issues and pull requests to make it easy to find them and to signal what needs to be done. Some of these are assigned by the developers, others by QA, bug triagers, project lead or maintainers and so on. It is not desired that users/reporters of bugs assign labels themselves, unless they are developers/contributors to Nextcloud.
The most important labels and their meaning:
* #backport-request - the pull requests also needs to be applied to older Nextcloud versions
* #bug - this issue is a bug
* #enhancement - this issue is a feature request/idea for improvement of Nextcloud
* #design - this needs help from the design team or is a design-related issue/pull request
* #technical debt - this issue or PR is about `technical debt <http://en.wikipedia.org/wiki/Technical_debt>`_
* #good first issue - these are issues which are relatively easy to solve and ideal for people who want to learn how to code in Nextcloud
* #needs info - this issue needs further information from the reporter, see :doc:`../bugtracker/triaging`
* #high #medium #low signify how important the bug is.
* Tags showing the state of the issue or PR, numbered 0-4:
* 0\. Needs triage - ready to start development on this
* 1\. to develop - ready to start development on this
* 2\. developing - development in progress
* 3\. to review - ready for review
* 4\. to release - reviewed PR that awaits unfreeze of a branch to get merged
* Feature tags: #feature: something. These tags indicate the features across apps and components which are impacted by the issue or which the PR is related to
If you want a label not in the list above, please first discuss on the mailing list.
Coding
------
* Maximum line-length of 80 characters
* Use tabs to indent
* A tab is 4 spaces wide
* Opening braces of blocks are on the same line as the definition
* Quotes: ' for everything, " for HTML attributes (<p class="my_class">)
* End of Lines : Unix style (LF / '\n') only
* No global variables or functions
* Unit tests
* HTML should be HTML5 compliant
* Check these `database performance tips <https://mailman.owncloud.org/pipermail/devel/2014-June/000262.html>`_
* When you ``git pull``, always ``git pull --rebase`` to avoid generating extra commits like: *merged master into master*
License headers
---------------
Nextcloud is licensed under the `GNU AGPLv3 <https://www.gnu.org/licenses/agpl>`_. From June, 16 2016 on we switched to "GNU AGPLv3 or any later version" for better long-term maintainability. If you create a new file please use this header:
.. code-block:: php
/**
*
* @copyright Copyright (c) <year>, <your name> (<your email address>)
*
* @license GNU AGPL version 3 or any later version
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
If you edit an existing file please add a copyright notice with your name, if you consider your changes substantial enough to claim copyright. As a rule if thumb, this is the case if you contributed more than seven lines of code.
User interface
--------------
* Software should get out of the way. Do things automatically instead of offering configuration options.
* Software should be easy to use. Show only the most important elements. Secondary elements only on hover or via Advanced function.
* User data is sacred. Provide undo instead of asking for confirmation - `which might be dismissed <http://www.alistapart.com/articles/neveruseawarning/>`_
* The state of the application should be clear. If something loads, provide feedback.
* Do not adapt broken concepts (for example design of desktop apps) just for the sake of consistency. We aim to provide a better interface, so let's find out how to do that!
* Regularly reset your installation to see how the first-run experience is like. And improve it.
* Ideally do `usability testing <http://jancborchardt.net/usability-in-free-software>`_ to know how people use the software.
* For further UX principles, read `Alex Faaborg from Mozilla <http://uxmag.com/articles/quantifying-usability>`_.
PHP
---
Starting with Nextcloud 19 there is a shared `PHP Coding Standards Fixer <https://github.com/FriendsOfPhp/PHP-CS-Fixer>`_ configuration you can use to automatically format your app's source code. For full details see the `repository on Github <https://github.com/nextcloud/coding-standard/>`_.
Always use::
<?php
at the start of your php code. The final closing::
?>
should not be used at the end of the file due to the `possible issue of sending white spaces <http://stackoverflow.com/questions/4410704/php-closing-tag>`_.
Comments
^^^^^^^^
All API methods need to be marked with `PHPDoc <http://en.wikipedia.org/wiki/PHPDoc>`_ markup. An example would be:
.. code-block:: php
<?php
/**
* Description what method does
* @param Controller $controller the controller that will be transformed
* @param API $api an instance of the API class
* @throws APIException if the api is broken
* @since 4.5
* @return string a name of a user
*/
public function myMethod(Controller $controller, API $api) {
// ...
}
Objects, functions, arrays & variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use *UpperCamelCase* for Objects, *lowerCamelCase* for functions and variables. If you set
a default function/method parameter, do not use spaces. Do not prepend private
class members with underscores.
.. code-block:: javascript
class MyClass {
}
function myFunction($default=null) {
}
$myVariable = 'blue';
$someArray = array(
'foo' => 'bar',
'spam' => 'ham',
);
?>
Operators
^^^^^^^^^
Use **===** and **!==** instead of **==** and **!=**.
Here's why:
.. code-block:: php
<?php
var_dump(0 == "a"); // 0 == 0 -> true
var_dump("1" == "01"); // 1 == 1 -> true
var_dump("10" == "1e1"); // 10 == 10 -> true
var_dump(100 == "1e2"); // 100 == 100 -> true
?>
Control structures
^^^^^^^^^^^^^^^^^^
* Always use { } for one line ifs
* Split long ifs into multiple lines
* Always use break in switch statements and prevent a default block with warnings if it shouldn't be accessed
.. code-block:: php
<?php
// single line if
if ($myVar === 'hi') {
$myVar = 'ho';
} else {
$myVar = 'bye';
}
// long ifs
if ( $something === 'something'
|| $condition2
&& $condition3
) {
// your code
}
// for loop
for ($i = 0; $i < 4; $i++) {
// your code
}
switch ($condition) {
case 1:
// action1
break;
case 2:
// action2;
break;
default:
// defaultaction;
break;
}
?>
Unit tests
^^^^^^^^^^
Unit tests must always extend the ``\Test\TestCase`` class, which takes care
of cleaning up the installation after the test.
If a test is run with multiple different values, a data provider must be used.
The name of the data provider method must not start with ``test`` and must end
with ``Data``.
.. code-block:: php
<?php
namespace Test;
class Dummy extends \Test\TestCase {
public function dummyData() {
return array(
array(1, true),
array(2, false),
);
}
/**
* @dataProvider dummyData
*/
public function testDummy($input, $expected) {
$this->assertEquals($expected, \Dummy::method($input));
}
}
JavaScript
----------
There is a shared configuration for `eslint <https://eslint.org/>`_ that you can use to automatically format your Nextcloud apps's JavaScript code. It consists of two parts: a `config package <https://github.com/nextcloud/eslint-config>`_ that contains the formatting preferences and a `plugin <https://github.com/nextcloud/eslint-plugin>`_ to detect deprecated and removed APIs in your code. See their readmes for instructions.
* Use a :file:`js/main.js` or :file:`js/app.js` where your program is started
* Use **const** or **let** to limit variable to local scope
* Use JavaScript strict mode
* Use a global namespace object where you bind publicly used functions and objects to
**DO**:
.. code-block:: javascript
// set up namespace for sharing across multiple files
var MyApp = MyApp || {};
(function(window, $, exports, undefined) {
'use strict';
// if this function or object should be global, attach it to the namespace
exports.myGlobalFunction = function(params) {
return params;
};
})(window, jQuery, MyApp);
**DONT** (Seriously):
.. code-block:: javascript
// This does not only make everything global but you're programming
// JavaScript like C functions with namespaces
MyApp = {
myFunction:function(params) {
return params;
},
...
};
Objects & inheritance
^^^^^^^^^^^^^^^^^^^^^
Try to use OOP in your JavaScript to make your code reusable and flexible.
This is how you'd do inheritance in JavaScript:
.. code-block:: javascript
// create parent object and bind methods to it
var ParentObject = function(name) {
this.name = name;
};
ParentObject.prototype.sayHello = function() {
console.log(this.name);
}
// create childobject, call parents constructor and inherit methods
var ChildObject = function(name, age) {
ParentObject.call(this, name);
this.age = age;
};
ChildObject.prototype = Object.create(ParentObject.prototype);
// overwrite parent method
ChildObject.prototype.sayHello = function() {
// call parent method if you want to
ParentObject.prototype.sayHello.call(this);
console.log('childobject');
};
var child = new ChildObject('toni', 23);
// prints:
// toni
// childobject
child.sayHello();
Objects, functions & variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use *UpperCamelCase* for Objects, *lowerCamelCase* for functions and variables.
.. code-block:: javascript
var MyObject = function() {
this.attr = "hi";
};
var myFunction = function() {
return true;
};
var myVariable = 'blue';
var objectLiteral = {
value1: 'somevalue'
};
Operators
^^^^^^^^^
Use **===** and **!==** instead of **==** and **!=**.
Here's why:
.. code-block:: javascript
'' == '0' // false
0 == '' // true
0 == '0' // true
false == 'false' // false
false == '0' // true
false == undefined // false
false == null // false
null == undefined // true
' \t\r\n ' == 0 // true
Control structures
^^^^^^^^^^^^^^^^^^
* Always use { } for one line ifs
* Split long ifs into multiple lines
* Always use break in switch statements and prevent a default block with warnings if it shouldn't be accessed
**DO**:
.. code-block:: javascript
// single line if
if (myVar === 'hi') {
myVar = 'ho';
} else {
myVar = 'bye';
}
// long ifs
if ( something === 'something'
|| condition2
&& condition3
) {
// your code
}
// for loop
for (var i = 0; i < 4; i++) {
// your code
}
// switch
switch (value) {
case 'hi':
// yourcode
break;
default:
console.warn('Entered undefined default block in switch');
break;
}
CSS
---
Take a look at the `Writing Tactical CSS & HTML <http://www.youtube.com/watch?v=hou2wJCh3XE&feature=plcp>`_ video on YouTube.
Don't bind your CSS too much to your HTML structure and try to avoid IDs. Also try to make your CSS reusable by grouping common attributes into classes.
**DO**:
.. code-block:: css
.list {
list-style-type: none;
}
.list > .list_item {
display: inline-block;
}
.important_list_item {
color: red;
}
**DON'T**:
.. code-block:: css
#content .myHeader ul {
list-style-type: none;
}
#content .myHeader ul li.list_item {
color: red;
display: inline-block;
}
**TBD**

89
developer_manual/getting_started/debugging.rst Normal file
View File

@@ -0,0 +1,89 @@
=========
Debugging
=========
Debug mode
----------
When debug mode is enabled in Nextcloud, a variety of debugging features are enabled - see debugging documentation. Set ``debug`` to ``true`` in :file:`/config/config.php` to enable it:
.. code-block:: php
<?php
$CONFIG = array (
'debug' => true,
... configuration goes here ...
);
Identifying errors
------------------
Nextcloud uses custom error PHP handling that prevents errors being printed to Web server log files or command line output. Instead, errors are generally stored in Nextcloud's own log file, located at: :file:`/data/nextcloud.log`
Debugging variables
-------------------
You should use exceptions if you need to debug variable values manually, and not alternatives like trigger_error() (which may not be logged).
e.g.:
.. code-block:: php
<?php throw new \Exception( "\$user = $user" ); // should be logged in Nextcloud ?>
not:
.. code-block:: php
<?php trigger_error( "\$user = $user" ); // may not be logged anywhere ?>
To disable custom error handling in Nextcloud (and have PHP and your Web server handle errors instead), see Debug mode.
Using a PHP debugger (XDebug)
-----------------------------
Using a debugger connected to PHP allows you to step through code line by line, view variables at each line and even change values while the code is running. The de-facto standard debugger for PHP is XDebug, available as an installable package in many distributions. It just provides the PHP side however, so you will need a frontend to actually control XDebug. When installed, it needs to be enabled in :file:`php.ini`, along with some parameters to enable connections to the debugging interface:
.. code-block:: ini
zend_extension=/usr/lib/php/modules/xdebug.so
xdebug.remote_enable=on
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
XDebug will now (when activated) try to connect to localhost on port 9000, and will communicate over the standard protocol DBGP. This protocol is supported by many debugging interfaces, such as the following popular ones:
- vdebug - Multi-language DBGP debugger client for Vim
- SublimeTextXdebug - XDebug client for Sublime Text
- PHPStorm - in-built DBGP debugger
For further reading, see the XDebug documentation: http://xdebug.org/docs/remote
Once you are familiar with how your debugging client works, you can start debugging with XDebug. To test Nextcloud through the web interface or other HTTP requests, set the ``XDEBUG_SESSION_START`` cookie or POST parameter. Alternatively, there are browser extensions to make this easy:
- The Easiest XDebug (Firefox): https://addons.mozilla.org/en-US/firefox/addon/the-easiest-xdebug/
- XDebug Helper (Chrome): https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc
For debugging scripts on the command line, like ``occ`` or unit tests, set the ``XDEBUG_CONFIG`` environment variable.
Debugging JavaScript
--------------------
By default all JavaScript files in Nextcloud are minified (compressed) into a single file without whitespace. To prevent this, see Debug mode.
Debugging HTML and templates
----------------------------
By default Nextcloud caches HTML generated by templates. This may prevent changes to app templates, for example, from being applied on page refresh. To disable caching, see Debug mode.
Using alternative app directories
---------------------------------
It may be useful to have multiple app directories for testing purposes, so you can conveniently switch between different versions of applications. See the configuration file documentation for details.

124
developer_manual/getting_started/devenv.rst Normal file
View File

@@ -0,0 +1,124 @@
.. _devenv:
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
=======================
Development environment
=======================
Please follow the steps on this page to set up your development environment.
Set up Web server and database
------------------------------
First `set up your Web server and database <https://docs.nextcloud.org/server/stable/admin_manual/installation/index.html>`_ (**Section**: Manual Installation - Prerequisites).
.. TODO ON RELEASE: Update version number above on release
Get the source
--------------
There are two ways to obtain Nextcloud sources:
* Using the `stable version <https://docs.nextcloud.org/server/stable/admin_manual/#installation>`_
* Using the development version from `GitHub`_ which will be explained below.
.. TODO ON RELEASE: Update version number above on release
To check out the source from `GitHub`_ you will need to install Git (see `Setting up Git <https://help.github.com/articles/set-up-git>`_ from the GitHub help)
Gather information about server setup
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To get started the basic Git repositories need to be cloned into the Web server's directory. Depending on the distribution this will either be
* **/var/www**
* **/var/www/html**
* **/srv/http**
Then identify the user and group the Web server is running as and the Apache user and group for the **chown** command will either be
* **http**
* **www-data**
* **apache**
* **wwwrun**
Check out the code
^^^^^^^^^^^^^^^^^^
The following commands are using **/var/www** as the Web server's directory and **www-data** as user name and group.
After the development tool installation make the directory writable so you install the code as your regular user, and don't need root privileges::
sudo chmod o+rw /var/www
Then install Nextcloud at the root of your site from Git::
git clone https://github.com/nextcloud/server.git /var/www/
cd /var/www
git submodule update --init
If you like to install Nextcloud at a sub-folder, replace `/var/www` with `/var/www/<folder>`.
Create the data and the config folders::
cd /var/www
mkdir data
mkdir config
Adjust rights::
cd /var/www
sudo chown -R www-data:www-data config data apps
sudo chmod o-rw /var/www
Finally restart the Web server (this might vary depending on your distribution)::
sudo systemctl restart httpd.service
or::
sudo systemctl restart apache2.service
or::
sudo /etc/init.d/apache2 restart
Now access the installation at http://localhost/ (or the corresponding URL) in your web browser to set up your instance.
Enabling debug mode
^^^^^^^^^^^^^^^^^^^
.. _debugmode:
.. note:: Do not enable this for production! This can create security problems and is only meant for debugging and development!
To disable JavaScript and CSS caching debugging has to be enabled by setting ``debug`` to ``true`` in :file:`config/config.php`::
<?php
$CONFIG = array (
'debug' => true,
... configuration goes here ...
);
Keep the code up-to-date
^^^^^^^^^^^^^^^^^^^^^^^^
If you have more than one repository cloned, it can be time consuming to do the same the action to all repositories one by one. To solve this, you can use the following command template::
find . -maxdepth <DEPTH> -type d -name .git -exec sh -c 'cd "{}"/../ && pwd && <GIT COMMAND>' \;
then, e.g. to pull all changes in all repositories, you only need this::
find . -maxdepth 3 -type d -name .git -exec sh -c 'cd "{}"/../ && pwd && git pull --rebase' \;
or to prune all merged branches, you would execute this::
find . -maxdepth 3 -type d -name .git -exec sh -c 'cd "{}"/../ && pwd && git remote prune origin' \;
It is even easier if you create alias from these commands in case you want to avoid retyping those each time you need them.
.. _GitHub: https://github.com/nextcloud
.. _GitHub Help Page: https://help.github.com/

9
developer_manual/getting_started/index.rst Normal file
View File

@@ -0,0 +1,9 @@
===============
Getting started
===============
.. toctree::
:maxdepth: 2
devenv
codingguidelines