From 8efccaf8598a274e363ad0344537357abaf0665d Mon Sep 17 00:00:00 2001 From: Jason Spriggs Date: Wed, 12 Dec 2012 21:14:33 -0500 Subject: [PATCH] Base commit for 4 files Code Reviews Kanban Styleguide Translation --- developer_manual/codereviews.rst | 49 +++++++++++++++++ developer_manual/index.rst | 5 +- developer_manual/kanban.rst | 4 ++ developer_manual/styleguide.rst | 6 +++ developer_manual/translation.rst | 90 ++++++++++++++++++++++++++++++++ 5 files changed, 153 insertions(+), 1 deletion(-) create mode 100644 developer_manual/codereviews.rst create mode 100644 developer_manual/kanban.rst create mode 100644 developer_manual/styleguide.rst create mode 100644 developer_manual/translation.rst diff --git a/developer_manual/codereviews.rst b/developer_manual/codereviews.rst new file mode 100644 index 000000000..8bf69a66e --- /dev/null +++ b/developer_manual/codereviews.rst @@ -0,0 +1,49 @@ +Code Reviews on github +====================== + +``We will start with a test phase for the next 2 month (until end of December). +The test phase will ONLY apply for the `core repository`_ at the moment. +(Other repositories are welcome to join ) +Let's see if we get any benefit from this approach.`` + +Linus’ Law: *“given enough eyeballs, all bugs are shallow”* + +Introduction +------------ + +In order to increase the code quality within ownCloud, developers are requested to perform code reviews. +As we are now heavily using the github platform these code review shall take place on github as well. + +Precondition +------------ + +From now on no direct commits/pushes to master or any of the stable branches are allowed in general. +**Every code** change – **even one liners** – have to be reviewed! + +How will it work? +----------------- + +#. A developer will submit his changes on github via a pull request. `github:help – using pull requests`_ +#. Within the pull request the developer could already name other developers (using @githubusername) and ask them for review. +#. Other developers (either named or at free will) have a look at the changes and are welcome to write comments within the comment field. +#. In case the reviewer is okay with the changes and thinks all his comments and suggestions have been take into account a :+1 on the comment will signal a positive review. +#. Before a pull request will be merged into master or the corresponding branch at least 2 reviewers need to give :+1 score. +#. In the near future we will have the `continuous integration server`_ set up to monitor pull request as well which will give an additional indicator for the quality. + +Examples +-------- + +Please find the first good examples below! +https://github.com/owncloud/core/pull/121 +https://github.com/owncloud/core/pull/146 + +Questions? +---------- + +Feel free to drop a line on the `mailing list`_ or join us on `IRC`_. + +.. _core repository: https://github.com/owncloud/core +.. _github:help – using pull requests: https://help.github.com/articles/using-pull-requests +.. _continuous integration server: https://ci.tmit.eu/ +.. _mailing list: https://mail.kde.org/mailman/listinfo/owncloud +.. _IRC: http://webchat.freenode.net/?channels=owncloud-dev \ No newline at end of file diff --git a/developer_manual/index.rst b/developer_manual/index.rst index 683475280..6c5341ac6 100644 --- a/developer_manual/index.rst +++ b/developer_manual/index.rst @@ -9,7 +9,10 @@ Contents debugging apps guidelines - + styleguide + codereviews + kanban + translation Indices and tables diff --git a/developer_manual/kanban.rst b/developer_manual/kanban.rst new file mode 100644 index 000000000..c0c61735a --- /dev/null +++ b/developer_manual/kanban.rst @@ -0,0 +1,4 @@ +Kanban Board +============ + +See http://owncloud.org/dev/kanban-board/ \ No newline at end of file diff --git a/developer_manual/styleguide.rst b/developer_manual/styleguide.rst new file mode 100644 index 000000000..f033bd362 --- /dev/null +++ b/developer_manual/styleguide.rst @@ -0,0 +1,6 @@ +Coding Style Guide +================== + +*Note: this is work-in-progress! We are currently building up this style guide and it’s topic of discussion.* + +See http://owncloud.org/dev/coding-style-guide/ \ No newline at end of file diff --git a/developer_manual/translation.rst b/developer_manual/translation.rst new file mode 100644 index 000000000..39ec25e82 --- /dev/null +++ b/developer_manual/translation.rst @@ -0,0 +1,90 @@ +Translation +=========== + +Make text translatable +---------------------- + +In HTML or PHP wrap it like this t('This is some text');?> +For the right date format use l('date', time());?>. Change the way dates are shown by editing /core/l10n/l10n-[lang].php +To translate text in javascript use: t('appname','text to translate'); + +You shall never split sentences! +-------------------------------- + +Reason: +~~~~~~~ + +Translators loose the context and they have no chance to possible re-arrange words. + +Example: +~~~~~~~~ + +``t('Select file from') . ' '; ?>t('local filesystem');?>t(' or '); ?>t('cloud');?>`` + +Translators will translate: +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Select file from +* local filesystem +* ‘ or ‘ +* cloud +By translating these individual strings for sure the case will be lost of “local filesystem” and “cloud”. The two white spaces with the or will get lost while translating as well. + +Html on translation string: +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Html tags in translation strings is ugly but usually translators can handle this. + +What about variable in the strings? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In case you need to add variables to the translation strings do it like that: +`` $l->t('%s is available. Get more information',array($data['versionstring'], $data['web']));`` + +Automated synchronization of translations +----------------------------------------- + +Multiple nightly jobs have been setup in order to synchronize translations – it’s a multi-step process: +‘perl l10n.pl read’ will rescan all php and javascript files and generate the templates. +The templates are pushed to `Transifex`_ (tx push -s). +All translations are pulled from `Transifex`_ (tx pull -a). +‘perl l10n.pl write’ will write the php files containing the translations. +Finally the changes are pushed to git. + +Please follow the steps below to add translation support to your app: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create a folder ‘l10n’. +Create the file ‘ignorelist’ which can contain files which shall not be scanned during step 4. +Edit ‘l10n/.tx/config’ and copy/past a config section and adopt it by changing the app/folder name. +Run ‘perl l10n.pl read’ with l10n +Add the newly created translation template (l10n/Templates/.pot) to git and commit the changes above. +After the next nightly sync job a new resource will appear on Transifex and from now on every night the latest translations will arrive. + +Translation sync jobs: +~~~~~~~~~~~~~~~~~~~~~~ + +http://ci.tmit.eu/job/ownCloud-core-tx/ +http://ci.tmit.eu/job/ownCloud-apps-tx/ +http://ci.tmit.eu/job/ownCloud-Mirall-tx/ + +**Caution: information below is in general not needed!** + +Manual quick translation update: +-------------------------------- + +``cd l10n/ && perl l10n.pl read && tx push -s && tx pull -a && perl l10n.pl write && cd ..`` + +The translation script requires Locale::PO, installable via ``apt-get install liblocale-po-perl`` + +Configure transifex +------------------- + +``tx init + +for resource in calendar contacts core files media gallery settings +do +tx set --auto-local -r owncloud.$resource "/$resource.po" --source-language=en \ + --source-file "templates/$resource.pot" --execute +done`` + +.. _Transifex: https://www.transifex.net/projects/p/owncloud/ \ No newline at end of file