"Fossies" - the Fresh Open Source Software Archive

Member "roundup-2.0.0/share/doc/roundup/html/_sources/developers.txt" (29 Jun 2020, 17512 Bytes) of package /linux/www/roundup-2.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "developers.txt": 1.6.1_vs_2.0.0.

    1 ==================
    2 Developing Roundup
    3 ==================
    4 
    5 .. note::
    6    The intended audience of this document is the developers of the core
    7    Roundup code. If you just wish to alter some behaviour of your Roundup
    8    installation, see `customising roundup`_.
    9 
   10 Contents
   11 
   12 .. contents::
   13    :local:
   14 
   15 Getting Started
   16 ---------------
   17 
   18 Anyone wishing to help in the development of Roundup must read `Roundup's
   19 Design Document`_ and the `implementation notes`_.
   20 
   21 All development is coordinated through two resources:
   22 
   23 - roundup-devel mailing list at
   24   https://sourceforge.net/projects/roundup/lists/roundup-devel
   25 - The issue tracker running at
   26   https://issues.roundup-tracker.org/
   27 
   28 Website, wiki
   29 -------------
   30 
   31 The website is in our repository, so is the configuration of the wiki.
   32 Please check the README.txt in the "website" subdirectory 
   33 of a current checkout.
   34 
   35 Issue Tracker
   36 -------------
   37 
   38 The tracker resides on bugs.ams1.psf.io (188.166.48.69). You can also
   39 ssh to issues.roundup-tracker.org. They have the same fingerprint:
   40 
   41     ED25519 key fingerprint is f1:f7:3d:bf:3b:01:8d:e1:4e:30:b3:0f:6e:98:b8:9b.
   42 
   43 The roundup installation belongs to the user roundup. 
   44 The setup uses virtualenv. Use the python version:
   45 
   46   /srv/roundup/env/bin/python2.7
   47 
   48 to get a python with roundup on the PYTHONPATH.
   49 
   50 The Roundup tracker https://issues.roundup-tracker.org/ is in
   51 /srv/roundup/trackers/roundup/ with the database set to
   52 /srv/roundup/data/roundup/. Note that postgres is used for the
   53 backend, so the database directory above is used for msgs and files.
   54 
   55 Source is in: /srv/roundup/src/
   56 
   57 Roundup is run using gunicorn and wsgi.
   58 
   59 You have 'sudo -u roundup' access if you need to run things as the
   60 roundup user.
   61 
   62 The configuration is in the "website/issues" section of Roundup's
   63 Mercurical SCM repository and copied manually to the live tracker.
   64 
   65   * get a working copy of roundup/website/issues from the SCM, either via
   66         hg clone https://hg.code.sf.net/p/roundup/code
   67     or download a snapshot:
   68         https://sourceforge.net/p/roundup/code/ci/default/tarball
   69 
   70   * check the differences
   71       diff -ur /srv/roundup/trackers/roundup/ roundup/website/issues/
   72 
   73 Copy differences using 'sudo -u roundup ...'.
   74 
   75 Getting a user account
   76 ~~~~~~~~~~~~~~~~~~~~~~
   77 
   78 To get access to the host, submit a pull request for:
   79 
   80     https://github.com/python/psf-salt
   81 
   82 by forking the repo, make a change similar to:
   83 
   84     https://github.com/rouilj/psf-salt/commit/2aa55d0fc5a343f45f5507437d3fba077cbaf852
   85 
   86 and submit it as a pull request. Contact ewdurbin via #roundup IRC or by
   87 adding an issue to the master psf-salt repo.
   88 
   89 
   90 Small Changes
   91 -------------
   92 
   93 Most small changes can be submitted as patches through the
   94 `issue tracker`_ or sent to `roundup-devel mailing list`_.
   95 
   96 
   97 Source Repository Access
   98 ------------------------
   99 
  100 See http://www.roundup-tracker.org/code.html.
  101 For all other questions ask on the development mailinglist.
  102 
  103 
  104 Project Rules
  105 -------------
  106 
  107 Mostly the project follows Guido's Style (though naming tends to be a little
  108 relaxed sometimes). In short:
  109 
  110 - 80 column width code
  111 - 4-space indentations
  112 - All modules must have an Id line near the top
  113 
  114 Other project rules:
  115 
  116 - New functionality must be documented, even briefly (so at least we know
  117   where there's missing documentation) and changes to tracker configuration
  118   must be logged in the upgrading document.
  119 - subscribe to roundup-checkins to receive checkin notifications from the
  120   other developers with write access to the source-code repository.
  121 - discuss any changes with the other developers on roundup-dev. If nothing
  122   else, this makes sure there's no rude shocks
  123 - write unit tests for changes you make (where possible), and ensure that
  124   all unit tests run before committing changes
  125 - run pychecker over changed code
  126 
  127 The administrators of the project reserve the right to boot developers who
  128 consistently check in code which is either broken or takes the codebase in
  129 directions that have not been agreed to.
  130 
  131 
  132 Debugging Aids
  133 --------------
  134 
  135 See :doc:`debugging <debugging>`.
  136 
  137 Internationalization Notes
  138 --------------------------
  139 
  140 How stuff works:
  141 
  142 1. Strings that may require translation (messages in human language)
  143    are marked in the source code.  This step is discussed in
  144    `Marking Strings for Translation`_ section.
  145 
  146 2. These strings are all extracted into Message Template File
  147    ``locale/roundup.pot`` (_`POT` file).  See `Extracting Translatable
  148    Messages`_ below.
  149 
  150 3. Language teams use POT file to make Message Files for national
  151    languages (_`PO` files).  All PO files for Roundup are kept in
  152    the ``locale`` directory.  Names of these files are target
  153    locale names, usually just 2-letter language codes.  `Translating
  154    Messages`_ section of this chapter gives useful hints for
  155    message translators.
  156 
  157 4. Translated Message Files are compiled into binary form (_`MO` files)
  158    and stored in ``locale`` directory (but not kept in the source code
  159    repository, as they may be easily made from PO files).
  160    See `Compiling Message Catalogs`_ section.
  161 
  162 5. Roundup installer creates runtime locale structure on the file
  163    system, putting MO files in their appropriate places.
  164 
  165 6. Runtime internationalization (_`I18N`) services use these MO files
  166    to translate program messages into language selected by current
  167    Roundup user.  Roundup command line interface uses locale name
  168    set in OS environment variable ``LANGUAGE``, ``LC_ALL``,
  169    ``LC_MESSAGES``, or ``LANG`` (in that order).  Roundup Web User
  170    Interface uses language selected by currently authenticated user.
  171 
  172 Additional details may be found in `GNU gettext`_ and Python `gettext
  173 module`_ documentation.
  174 
  175 `Roundup source distribution`_ includes POT and PO files for message
  176 translators, and also pre-built MO files to facilitate installations
  177 from source.  Roundup binary distribution includes MO files only.
  178 
  179 .. _GNU gettext:
  180 
  181 GNU gettext package
  182 ~~~~~~~~~~~~~~~~~~~
  183 
  184 This chapter is full of references to GNU `gettext package`_.
  185 GNU gettext is a "must have" for nearly all steps of internationalizing
  186 any program, and it's manual is definetely a recommended reading
  187 for people involved in `I18N`_.
  188 
  189 There are GNU gettext ports to all major OS platforms.
  190 Windows binaries are available from `GNU mirror sites`_.
  191 
  192 Roundup does not use GNU gettext at runtime, but it's tools
  193 are used for `extracting translatable messages`_, `compiling
  194 message catalogs`_ and, optionally, for `translating messages`_.
  195 
  196 Note that ``gettext`` package in some OS distributions means just
  197 runtime tools and libraries.  In such cases gettext development tools
  198 are usually distributed in separate package named ``gettext-devel``.
  199 
  200 Marking Strings for Translation
  201 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  202 
  203 Strings that need translation must be marked in the source code.
  204 Following subsections explain how this is done in different cases.
  205 
  206 If translatable string is used as a format string, it is recommended
  207 to always use *named* format specifiers::
  208 
  209   _('Index of %(classname)s') % locals()
  210 
  211 This helps translators to better understand the context of the
  212 message and, with Python formatting, remove format specifier altogether
  213 (which is sometimes useful, especially in singular cases of `Plural Forms`_).
  214 
  215 When there is more than one format specifier in the translatable
  216 format string, named format specifiers **must** be used almost always,
  217 because translation may require different order of items.
  218 
  219 It is better to *not* mark for translation strings that are not
  220 locale-dependent, as this makes it more difficult to keep track
  221 of translation completeness.  For example, string ``</ol></body></html>``
  222 (in ``index()`` method of the request handler in ``roundup_server``
  223 script) has no human readable parts at all, and needs no translations.
  224 Such strings are left untranslated in PO files, and are reported
  225 as such by PO status checkers (e.g. ``msgfmt --statistics``).
  226 
  227 Command Line Interfaces
  228 ~~~~~~~~~~~~~~~~~~~~~~~
  229 
  230 Scripts and routines run from the command line use "static" language
  231 defined by environment variables recognized by ``gettext`` module
  232 from Python library (``LANGUAGE``, ``LC_ALL``, ``LC_MESSAGES``, and
  233 ``LANG``).  Primarily, these are ``roundup-admin`` script and
  234 ``admin.py`` module, but also help texts and startup error messages
  235 in other scripts and their supporting modules.
  236 
  237 For these interfaces, Python ``gettext`` engine must be initialized
  238 to use Roundup message catalogs.  This is normally done by including
  239 the following line in the module imports::
  240 
  241   from i18n import _, ngettext
  242 
  243 Simple translations are automatically marked by calls to builtin
  244 message translation function ``_()``::
  245 
  246   print(_("This message is translated"))
  247 
  248 Translations for messages whose grammatical depends on a number
  249 must be done by ``ngettext()`` function::
  250 
  251   print(ngettext("Nuked %i file", "Nuked %i files", number_of_files_nuked))
  252 
  253 Deferred Translations
  254 ~~~~~~~~~~~~~~~~~~~~~
  255 
  256 Sometimes translatable strings appear in the source code in untranslated
  257 form [#note_admin.py]_ and must be translated elsewhere.
  258 Example::
  259 
  260   for meal in ("spam", "egg", "beacon"):
  261       print(_(meal))
  262 
  263 In such cases, strings must be marked for translation without actual
  264 call to the translating function.  To mark these strings, we use Python
  265 feature of automatic concatenation of adjacent strings and different
  266 types of string quotes::
  267 
  268   strings_to_translate = (
  269       ''"This string will be translated",
  270       ""'me too',
  271       ''r"\raw string",
  272       ''"""
  273       multiline string"""
  274   )
  275 
  276 .. [#note_admin.py] In current Roundup sources, this feature is
  277    extensively used in the ``admin`` module using method docstrings
  278    as help messages.
  279 
  280 Web User Interface
  281 ~~~~~~~~~~~~~~~~~~
  282 
  283 For Web User Interface, translation services are provided by Client
  284 object.  Action classes have methods ``_()`` and ``gettext()``,
  285 delegating translation to the Client instance.  In HTML templates,
  286 translator object is available as context variable ``i18n``.
  287 
  288 HTML templates have special markup for translatable strings.
  289 The syntax for this markup is defined on `ZPTInternationalizationSupport`_
  290 page.  Roundup translation service currently ignores values for
  291 ``i18n:domain``, ``i18n:source`` and ``i18n:target``.
  292 
  293 Template markup examples:
  294 
  295 * simplest case::
  296 
  297     <div i18n:translate="">
  298      Say
  299      no
  300      more!
  301     </div>
  302 
  303   this will result in msgid ``"Say no more!"``, with all leading and
  304   trailing whitespace stripped, and inner blanks replaced with single
  305   space character.
  306 
  307 * using variable slots::
  308 
  309     <div i18n:translate="">
  310      And now...<br/>
  311      No.<span tal:replace="number" i18n:name="slideNo" /><br/>
  312      THE LARCH
  313     </div>
  314 
  315   Msgid will be: ``"And now...<br /> No.${slideNo}<br /> THE LARCH"``.
  316   Template rendering will use context variable ``number`` (you may use
  317   any expression) to put instead of ``${slideNo}`` in translation.
  318 
  319 * attribute translation::
  320 
  321     <button name="btn_wink" value=" Wink " i18n:attributes="value" />
  322 
  323   will translate the caption (and return value) for the "wink" button.
  324 
  325 * explicit msgids.  Sometimes it may be useful to specify msgid
  326   for the element translation explicitely, like this::
  327 
  328     <span i18n:translate="know what i mean?">this text is ignored</span>
  329 
  330   When rendered, element contents will be replaced by translation
  331   of the string specified in ``i18n:translate`` attribute.
  332 
  333 * ``i18n`` in `TALES`_.  You may translate strings in `TALES`_ python
  334   expressions::
  335 
  336     <span tal:replace="python: i18n.gettext('Oh, wicked.')" />
  337 
  338 * plural forms.  There is no markup for plural forms in `TAL`_ i18n.
  339   You must use python expression for that::
  340 
  341     <span tal:replace="python: i18n.ngettext(
  342       'Oh but it\'s only %i shilling.',
  343       'Oh but it\'s only %i shillings.',
  344       fine) % fine"
  345     />
  346 
  347 Extracting Translatable Messages
  348 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  349 
  350 The most common tool for message extraction is ``xgettext`` utility
  351 from `GNU gettext package`_.  Unfortunately, this utility has no means
  352 of `Deferred Translations`_ in Python sources.  There is ``xpot`` tool
  353 from Francois Pinard free `PO utilities`_ that allows to mark strings
  354 for deferred translations, but it does not handle `plural forms`_.
  355 
  356 Roundup overcomes these limitations by using both of these utilities.
  357 This means that you need both `GNU gettext`_ tools and `PO utilities`_
  358 to build the Message Template File yourself.
  359 
  360 Latest Message Template File is kept in the source code repository 
  361 and distributed with `Roundup Source`_.  
  362 If you wish to rebuild the template yourself,
  363 make sure that you have both ``xpot`` and ``xgettext`` installed and
  364 just run ``gmake`` (or ``make``, if you are on a `GNU`_ system like
  365 `linux`_ or `cygwin`_) in the ``locale`` directory.
  366 
  367 For on-site i18n, Roundup provides command-line utility::
  368 
  369   roundup-gettext <tracker_home>
  370 
  371 extracting translatable messages from tracker's html templates.
  372 This utility creates message template file ``messages.pot`` in
  373 ``locale`` subdirectory of the tracker home directory.  Translated
  374 messages may be put in *locale*.po files (where *locale* is selected
  375 locale name) in the same directory, e.g.: ``locale/ru.po``.
  376 These message catalogs are searched prior to system-wide translations
  377 kept in the ``share`` directory.
  378 
  379 Translating Messages
  380 ^^^^^^^^^^^^^^^^^^^^
  381 
  382 Gettext Message File (`PO`_ file) is a plain text file, that can be created
  383 by simple copying ``roundup.pot`` to new .po file, like this::
  384 
  385   $ cp roundup.pot ru.po
  386 
  387 The name of PO file is target locale name, usually just 2-letter language
  388 code (``ru`` for Russian in the above example).  Alternatively, PO file
  389 may be initialized by ``msginit`` utility from `GNU gettext`_ tools::
  390 
  391   $ msginit -i roundup.pot
  392 
  393 ``msginit`` will check your current locale, and initialize the header
  394 entry, setting language name, rules for `plural forms`_ and, if available,
  395 translator's name and email address.  The name for PO file is also chosen
  396 based on current locale.
  397 
  398 Next, you will need to edit this file, filling all ``msgstr`` lines with
  399 translations of the above ``msgid`` entries.  PO file is a plain text
  400 file that can be edited with any text editor.  However, there are several
  401 tools that may help you with this process:
  402 
  403  - `poEdit`_ by Vaclav Slavik.  Very nice cross-platform GUI editor.
  404 
  405  - `Lokalize`_. A replacement for KBabel. Being part of `KDE`_, it
  406     works in X windows only. Haven't had much experience with it, though.
  407 
  408  - ``po-mode`` for `emacs`_.  One of `GNU gettext`_ tools.  Very handy,
  409    definitely recommended if you are comfortable with emacs.  Cannot
  410    handle `plural forms`_ per se, but allows to edit them in simple
  411    text mode.
  412 
  413  - `po filetype plugin`_ for `vim`_.  Does not do as much as ``po-mode``,
  414    but helps in finding untranslated and fuzzy strings, and checking
  415    code references.  Please contact `alexander smishlajev`_ if you
  416    prefer this, as i have patched this plugin a bit.  I have also
  417    informed the original plugin author about these changes, but got
  418    no reply so far.
  419 
  420 Compiling Message Catalogs
  421 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  422 
  423 Message catalogs (`PO`_ files) must be compiled into binary form
  424 (`MO`_ files) before they can be used in the application.  This
  425 compilation is handled by ``msgfmt`` utility from `GNU gettext`_
  426 tools.  ``GNUmakefile`` in the ``locale`` directory automatically
  427 compiles all existing message catalogs after updating them from
  428 Roundup source files.  If you wish to rebuild an individual `MO`_
  429 file without making everything else, you may, for example::
  430 
  431   $ msgfmt --statistics -o ru.mo ru.po
  432 
  433 This way, message translators can check their `PO`_ files without
  434 extracting strings from source.  (Note: String extraction requires
  435 additional utility that is not part of `GNU gettext`_.  See `Extracting
  436 Translatable Messages`_.)
  437 
  438 At run time, Roundup automatically compiles message catalogs whenever
  439 `PO`_ file is changed.
  440 
  441 .. _`Customising Roundup`: customizing.html
  442 .. _`Roundup's Design Document`: spec.html
  443 .. _`implementation notes`: implementation.html
  444 
  445 
  446 .. _External hyperlink targets:
  447 
  448 .. _alexander smishlajev:
  449 .. _als: https://sourceforge.net/u/a1s/profile/
  450 .. _cygwin: https://www.cygwin.com/
  451 .. _emacs: https://www.gnu.org/software/emacs/
  452 .. _gettext package: http://www.gnu.org/savannah-checkouts/gnu/gettext/manual/gettext.html
  453 .. _gettext module: https://docs.python.org/2/library/gettext.html
  454 .. _GNU: http://www.gnu.org/
  455 .. _GNU mirror sites: http://www.gnu.org/prep/ftp.html
  456 .. _issue tracker: https://issues.roundup-tracker.org/
  457 .. _Lokalize: Lokalize
  458 .. _KDE: https://kde.org/
  459 .. _linux: https://www.linux.org/
  460 .. _Plural Forms:
  461     http://www.gnu.org/savannah-checkouts/gnu/gettext/manual/gettext.html
  462 .. _po filetype plugin:
  463     https://vim.sourceforge.io/scripts/script.php?script_id=695
  464 .. _PO utilities: https://github.com/pinard/po-utils
  465 .. _poEdit: https://poedit.net/
  466 .. _Roundup Source:
  467 .. _Roundup source distribution:
  468 .. _Roundup binary distribution:
  469     https://sourceforge.net/projects/roundup/files/
  470 .. _roundup-devel mailing list:
  471    https://sourceforge.net/projects/roundup/lists/roundup-devel
  472 .. _TAL:
  473 .. _Template Attribute Language:
  474    https://pagetemplates.readthedocs.io/en/latest/history/TALSpecification14.html
  475 .. _TALES:
  476 .. _Template Attribute Language Expression Syntax:
  477    https://pagetemplates.readthedocs.io/en/latest/history/TALESSpecification13.html
  478 .. _vim: https://www.vim.org/
  479 .. _ZPTInternationalizationSupport: http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/ZPTInternationalizationSupport
  480