# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2013, Various
# This file is distributed under the same license as the Elgg package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Elgg master\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2021-07-09 15:46+0200\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#: ../../contribute/code.rst:2
msgid "Writing Code"
msgstr ""

#: ../../contribute/code.rst:4
msgid "Understand Elgg's standards and processes to get your changes accepted as quickly as possible."
msgstr ""

#: ../../contribute/code.rst:8
#: ../../contribute/core/move_plugin.rst:6
#: ../../contribute/core/releases.rst:12
#: ../../contribute/database.rst:8
#: ../../contribute/docs.rst:8
#: ../../contribute/tests.rst:6
msgid "Contents"
msgstr ""

#: ../../contribute/code.rst:11
msgid "License agreement"
msgstr ""

#: ../../contribute/code.rst:13
msgid "By submitting a patch you are agreeing to license the code under a `GPLv2 license`_ and `MIT license`_."
msgstr ""

#: ../../contribute/code.rst:20
msgid "Pull requests"
msgstr ""

#: ../../contribute/code.rst:22
msgid "Pull requests (PRs) are the best way to get code contributed to Elgg core. The core development team uses them even for the most trivial changes."
msgstr ""

#: ../../contribute/code.rst:25
msgid "For new features, `submit a feature request <https://github.com/Elgg/Elgg/issues>`__ or `talk to us`_ first and make sure the core team approves of your direction before spending lots of time on code."
msgstr ""

#: ../../contribute/code.rst:31
msgid "Checklists"
msgstr ""

#: ../../contribute/code.rst:33
msgid "Use these markdown checklists for new PRs on github to ensure high-quality contributions and help everyone understand the status of open PRs."
msgstr ""

#: ../../contribute/code.rst:36
msgid "Bugfix PRs:"
msgstr ""

#: ../../contribute/code.rst:46
msgid "Feature PRs:"
msgstr ""

#: ../../contribute/code.rst:58
msgid "Choosing a branch to submit to"
msgstr ""

#: ../../contribute/code.rst:60
msgid "The following table assumes the latest stable release is 2.1."
msgstr ""

#: ../../contribute/code.rst:63
msgid "Type of change"
msgstr ""

#: ../../contribute/code.rst:63
msgid "Branch to submit against"
msgstr ""

#: ../../contribute/code.rst:65
msgid "Security fix"
msgstr ""

#: ../../contribute/code.rst:65
msgid "Don't! Email security@elgg.org for guidance."
msgstr ""

#: ../../contribute/code.rst:66
msgid "Bug fix"
msgstr ""

#: ../../contribute/code.rst:66
msgid "1.12 (or 2.1 if the 1.12 fix is too complex)"
msgstr ""

#: ../../contribute/code.rst:67
msgid "Performance"
msgstr ""

#: ../../contribute/code.rst:67
#: ../../contribute/code.rst:68
#: ../../contribute/code.rst:69
msgid "2.x"
msgstr ""

#: ../../contribute/code.rst:68
msgid "Deprecation"
msgstr ""

#: ../../contribute/code.rst:69
msgid "Minor feature"
msgstr ""

#: ../../contribute/code.rst:70
msgid "Major feature"
msgstr ""

#: ../../contribute/code.rst:70
#: ../../contribute/code.rst:71
msgid "master"
msgstr ""

#: ../../contribute/code.rst:71
msgid "Has any breaking change"
msgstr ""

#: ../../contribute/code.rst:74
msgid "If you're not sure which branch to submit against, just ask!"
msgstr ""

#: ../../contribute/code.rst:76
msgid "The difference between minor and major feature is subjective and up to the core team."
msgstr ""

#: ../../contribute/code.rst:79
msgid "Commit message format"
msgstr ""

#: ../../contribute/code.rst:81
msgid "We require a particular format to allow releasing more often, and with improved changelogs and source history. Just follow these steps:"
msgstr ""

#: ../../contribute/code.rst:84
msgid "Start with the ``type`` by selecting the *last category which applies* from this list:"
msgstr ""

#: ../../contribute/code.rst:86
msgid "**docs** - *only* docs are being updated"
msgstr ""

#: ../../contribute/code.rst:87
msgid "**chore** - this include refactoring, code style changes, adding missing tests, CI stuff, etc."
msgstr ""

#: ../../contribute/code.rst:88
msgid "**perf** - the primary purpose is to improve performance"
msgstr ""

#: ../../contribute/code.rst:89
msgid "**fix** - this fixes a bug"
msgstr ""

#: ../../contribute/code.rst:90
msgid "**deprecate** - the change deprecates any part of the API"
msgstr ""

#: ../../contribute/code.rst:91
msgid "**break** - the change breaks any part of the API"
msgstr ""

#: ../../contribute/code.rst:92
msgid "**feature** - this adds a new user-facing or developer feature"
msgstr ""

#: ../../contribute/code.rst:93
msgid "**removed** - this removes a user-facing or developer feature"
msgstr ""

#: ../../contribute/code.rst:94
msgid "**security** - the change affects a security issue in any way. *Please do not push this commit to any public repo.* Instead contact security@elgg.org."
msgstr ""

#: ../../contribute/code.rst:96
msgid "E.g. if your commit refactors to fix a bug, it's still a \"fix\". If that bug is security-related, however, the type must be \"security\" and you should email security@elgg.org before proceeding. When in doubt, make your best guess and a reviewer will provide guidance."
msgstr ""

#: ../../contribute/code.rst:100
msgid "In parenthesis, add the ``component``, a short string which describes the subsystem being changed."
msgstr ""

#: ../../contribute/code.rst:102
msgid "Some examples: ``views``, ``i18n``, ``seo``, ``a11y``, ``cache``, ``db``, ``session``, ``router``, ``<plugin_name>``."
msgstr ""

#: ../../contribute/code.rst:104
msgid "Add a colon, a space, and a brief ``summary`` of the changes, which will appear in the changelog."
msgstr ""

#: ../../contribute/code.rst:106
msgid "No line may exceed 100 characters in length, so keep your summary concise."
msgstr ""

#: ../../contribute/code.rst:109
msgid "Good summary"
msgstr ""

#: ../../contribute/code.rst:109
msgid "Bad summary (problem)"
msgstr ""

#: ../../contribute/code.rst:111
msgid "page owners see their own owner blocks on pages"
msgstr ""

#: ../../contribute/code.rst:111
msgid "bug fix (vague)"
msgstr ""

#: ../../contribute/code.rst:112
msgid "bar view no longer dies if 'foo' not set"
msgstr ""

#: ../../contribute/code.rst:112
msgid "updates views/default/bar.php so bar view no longer... (redundant info)"
msgstr ""

#: ../../contribute/code.rst:113
msgid "narrows river layout to fit iPhone"
msgstr ""

#: ../../contribute/code.rst:113
msgid "alters the river layout (vague)"
msgstr ""

#: ../../contribute/code.rst:114
msgid "elgg_foo() handles arrays for $bar"
msgstr ""

#: ../../contribute/code.rst:114
msgid "in elgg_foo() you can now pass an array for $bar and the function will... (move detail to description)"
msgstr ""

#: ../../contribute/code.rst:115
msgid "removes link color from comments header in river"
msgstr ""

#: ../../contribute/code.rst:115
msgid "fixes db so that... (redundant info)"
msgstr ""

#: ../../contribute/code.rst:116
msgid "requires non-empty title when saving pages"
msgstr ""

#: ../../contribute/code.rst:116
msgid "can save pages with no title (confusingly summarizes old behavior)"
msgstr ""

#: ../../contribute/code.rst:119
msgid "(recommended) Skip a line and add a ``description`` of the changes. Include the motivation for making them, any info about back or forward compatibility, and any rationale of why the change had to be done a certain way. Example:"
msgstr ""

#: ../../contribute/code.rst:122
msgid "We speed up the Remember Me table migration by using a single INSERT INTO ... SELECT query instead of row-by-row. This migration takes place during the upgrade to 1.9."
msgstr ""

#: ../../contribute/code.rst:125
msgid "Unless your change is trivial/obvious, a description is required."
msgstr ""

#: ../../contribute/code.rst:127
msgid "If the commit resolves a GitHub issue, skip a line and add ``Fixes #`` followed by the issue number. E.g. ``Fixes #1234``. You can include multiple issues by separating with commas."
msgstr ""

#: ../../contribute/code.rst:130
msgid "GitHub will auto-close the issue when the commit is merged. If you just want to reference an issue, use ``Refs #`` instead."
msgstr ""

#: ../../contribute/code.rst:133
msgid "When done, your commit message will have the format:"
msgstr ""

#: ../../contribute/code.rst:146
msgid "Here is an example of a good commit message:"
msgstr ""

#: ../../contribute/code.rst:158
msgid "Rewriting commit messages"
msgstr ""

#: ../../contribute/code.rst:159
msgid "If your PR does not conform to the standard commit message format, we'll ask you to rewrite it."
msgstr ""

#: ../../contribute/code.rst:161
msgid "To edit just the last commit:"
msgstr ""

#: ../../contribute/code.rst:163
msgid "Amend the commit: ``git commit --amend`` (git opens the message in a text editor)."
msgstr ""

#: ../../contribute/code.rst:164
msgid "Change the message and save/exit the editor."
msgstr ""

#: ../../contribute/code.rst:165
msgid "Force push your branch: ``git push -f your_remote your_branch`` (your PR with be updated)."
msgstr ""

#: ../../contribute/code.rst:166
#: ../../contribute/code.rst:175
msgid "Rename the PR title to match"
msgstr ""

#: ../../contribute/code.rst:168
msgid "Otherwise you may need to perform an interactive rebase:"
msgstr ""

#: ../../contribute/code.rst:170
msgid "Rebase the last N commits: ``git rebase -i HEAD~N`` where N is a number. (Git will open the ``git-rebase-todo`` file for editing)"
msgstr ""

#: ../../contribute/code.rst:172
msgid "For the commits that need to change, change ``pick`` to ``r`` (for reword) and save/exit the editor."
msgstr ""

#: ../../contribute/code.rst:173
msgid "Change the commit message(s), save/exit the editor (git will present a file for each commit that needs rewording)."
msgstr ""

#: ../../contribute/code.rst:174
msgid "``git push -f your_remote your_branch`` to force push the branch (updating your PR)."
msgstr ""

#: ../../contribute/code.rst:181
msgid "Coding Standards"
msgstr ""

#: ../../contribute/code.rst:183
msgid "Elgg uses set of standards that are based partially on PEAR and PSR2 standards. You can view the ruleset in ``vendor/elgg/sniffs/elgg.xml``."
msgstr ""

#: ../../contribute/code.rst:185
msgid "To check your code for standard violations (provided you have installed Elgg with dev dependencies), run:"
msgstr ""

#: ../../contribute/code.rst:192
msgid "To automatically fix fixable violations, run:"
msgstr ""

#: ../../contribute/code.rst:202
msgid "Testing"
msgstr ""

#: ../../contribute/code.rst:204
msgid "Elgg has automated tests for both PHP and JavaScript functionality. All new contributions are required to come with appropriate tests."
msgstr ""

#: ../../contribute/code.rst:208
msgid ":doc:`tests`"
msgstr ""

#: ../../contribute/code.rst:211
msgid "General guidelines"
msgstr ""

#: ../../contribute/code.rst:213
msgid "Break tests up by the behaviors you want to test and use names that describe the behavior. E.g.:"
msgstr ""

#: ../../contribute/code.rst:215
msgid "Not so good: One big method ``testAdd()``."
msgstr ""

#: ../../contribute/code.rst:217
msgid "Better: Methods ``testAddingZeroChangesNothing`` and ``testAddingNegativeNumberSubtracts``"
msgstr ""

#: ../../contribute/code.rst:219
msgid "Strive for :ref:`componentized designs <contribute/code#solid>` that allow testing in isolation, without large dependency graphs or DB access. Injecting dependencies is key here."
msgstr ""

#: ../../contribute/code.rst:222
msgid "PHP Tests"
msgstr ""

#: ../../contribute/code.rst:225
msgid "PHPUnit"
msgstr ""

#: ../../contribute/code.rst:227
msgid "Located in ``engine/tests/phpunit``, this is our preferred test suite. It uses no DB access, and has only superficial access to the entities API."
msgstr ""

#: ../../contribute/code.rst:229
msgid "We encourage you to create components that are testable in this suite if possible."
msgstr ""

#: ../../contribute/code.rst:230
msgid "Consider separating storage from your component so at least business logic can be tested here."
msgstr ""

#: ../../contribute/code.rst:231
msgid "Depend on the ``Elgg\\Filesystem\\*`` classes rather than using PHP filesystem functions."
msgstr ""

#: ../../contribute/code.rst:234
msgid "Testing interactions between services"
msgstr ""

#: ../../contribute/code.rst:236
msgid "Ideally your tests would construct your own isolated object graphs for direct manipulation, but this isn't always possible."
msgstr ""

#: ../../contribute/code.rst:238
msgid "If your test relies on Elgg's Service Provider (``_elgg_services()`` returns a ``Elgg\\Di\\ServiceProvider``), realize that it maintains a singleton instance for most services it hands out, and many services keep their own local references to these services as well."
msgstr ""

#: ../../contribute/code.rst:240
msgid "Due to these local references, replacing services on the SP within a test often will not have the desired effect. Instead, you may need to use functionality baked into the services themselves:"
msgstr ""

#: ../../contribute/code.rst:242
msgid "The ``events`` and ``hooks`` services have methods ``backup()`` and ``restore()``."
msgstr ""

#: ../../contribute/code.rst:243
msgid "The ``logger`` service has methods ``disable()`` and ``enable()``."
msgstr ""

#: ../../contribute/code.rst:246
msgid "Jasmine Tests"
msgstr ""

#: ../../contribute/code.rst:248
msgid "Test files must be named ``*Test.js`` and should go in either ``js/tests/`` or next to their source files in ``views/default/**.js``. Karma will automatically pick up on new ``*Test.js`` files and run those tests."
msgstr ""

#: ../../contribute/code.rst:253
msgid "Test boilerplate"
msgstr ""

#: ../../contribute/code.rst:266
msgid "Running the tests"
msgstr ""

#: ../../contribute/code.rst:267
msgid "Elgg uses `Karma`_ with `Jasmine`_ to run JS unit tests."
msgstr ""

#: ../../contribute/code.rst:272
msgid "You will need to have nodejs and yarn installed."
msgstr ""

#: ../../contribute/code.rst:274
msgid "First install all the development dependencies:"
msgstr ""

#: ../../contribute/code.rst:280
msgid "Run through the tests just once and then quit:"
msgstr ""

#: ../../contribute/code.rst:286
msgid "You can also run tests continuously during development so they run on each save:"
msgstr ""

#: ../../contribute/code.rst:293
msgid "Debugging JS tests"
msgstr ""

#: ../../contribute/code.rst:295
msgid "You can run the test suite inside Chrome dev tools:"
msgstr ""

#: ../../contribute/code.rst:301
msgid "This will output a URL like ``http://localhost:9876/``."
msgstr ""

#: ../../contribute/code.rst:303
msgid "Open the URL in Chrome, and click \"Debug\"."
msgstr ""

#: ../../contribute/code.rst:304
msgid "Open Chrome dev tools and the Console tab."
msgstr ""

#: ../../contribute/code.rst:305
msgid "Reload the page."
msgstr ""

#: ../../contribute/code.rst:307
msgid "If you alter a test you'll have to quit Karma with ``Ctrl-c`` and restart it."
msgstr ""

#: ../../contribute/code.rst:310
msgid "Coding best practices"
msgstr ""

#: ../../contribute/code.rst:312
msgid "Make your code easier to read, easier to maintain, and easier to debug. Consistent use of these guidelines means less guess work for developers, which means happier, more productive developers."
msgstr ""

#: ../../contribute/code.rst:318
msgid "General coding"
msgstr ""

#: ../../contribute/code.rst:321
msgid "Don't Repeat Yourself"
msgstr ""

#: ../../contribute/code.rst:323
msgid "If you are copy-pasting code a significant amount of code, consider whether there's an opportunity to reduce duplication by introducing a function, an additional argument, a view, or a new component class."
msgstr ""

#: ../../contribute/code.rst:326
msgid "E.g. If you find views that are identical except for a single value, refactor into a single view that takes an option."
msgstr ""

#: ../../contribute/code.rst:329
msgid "**Note:** In a bugfix release, *some duplication is preferrable to refactoring*. Fix bugs in the simplest way possible and refactor to reduce duplication in the next minor release branch."
msgstr ""

#: ../../contribute/code.rst:335
msgid "Embrace SOLID and GRASP"
msgstr ""

#: ../../contribute/code.rst:337
msgid "Use these `principles for OO design`__ to solve problems using loosely coupled components, and try to make all components and integration code testable."
msgstr ""

#: ../../contribute/code.rst:343
msgid "Whitespace is free"
msgstr ""

#: ../../contribute/code.rst:345
msgid "Don't be afraid to use it to separate blocks of code. Use a single space to separate function params and string concatenation."
msgstr ""

#: ../../contribute/code.rst:349
msgid "Variable names"
msgstr ""

#: ../../contribute/code.rst:351
msgid "Use self-documenting variable names.  ``$group_guids`` is better than ``$array``."
msgstr ""

#: ../../contribute/code.rst:353
msgid "Avoid double-negatives. Prefer ``$enable = true`` to ``$disable = false``."
msgstr ""

#: ../../contribute/code.rst:356
msgid "Interface names"
msgstr ""

#: ../../contribute/code.rst:358
msgid "Use the pattern ``Elgg\\{Namespace}\\{Name}``."
msgstr ""

#: ../../contribute/code.rst:360
msgid "Do not include an ``I`` prefix or an ``Interface`` suffix."
msgstr ""

#: ../../contribute/code.rst:362
msgid "We do not include any prefix or suffix so that we're encouraged to:"
msgstr ""

#: ../../contribute/code.rst:364
msgid "name implementation classes more descriptively (the \"default\" name is taken)."
msgstr ""

#: ../../contribute/code.rst:365
msgid "type-hint on interfaces, because that is the shortest, easiest thing to do."
msgstr ""

#: ../../contribute/code.rst:367
msgid "Name implementations like ``Elgg\\{Namespace}\\{Interface}\\{Implementation}``."
msgstr ""

#: ../../contribute/code.rst:370
msgid "Functions"
msgstr ""

#: ../../contribute/code.rst:372
msgid "Where possible, have functions/methods return a single type. Use empty values such as ``array()``, ``\"\"``, or ``0`` to indicate no results."
msgstr ""

#: ../../contribute/code.rst:375
msgid "Be careful where valid return values (like ``\"0\"``) could be interpreted as empty."
msgstr ""

#: ../../contribute/code.rst:377
msgid "Functions not throwing an exception on error should return ``false`` upon failure."
msgstr ""

#: ../../contribute/code.rst:381
msgid "Particularly low-level, non-API functions/methods (e.g. entity_row_to_elggstar), which should not fail under normal conditions, should throw instead of returning false."
msgstr ""

#: ../../contribute/code.rst:384
msgid "Functions returning only boolean should be prefaced with ``is_`` or ``has_`` (eg, ``elgg_is_logged_in()``, ``elgg_has_access_to_entity()``)."
msgstr ""

#: ../../contribute/code.rst:388
msgid "Ternary syntax"
msgstr ""

#: ../../contribute/code.rst:390
msgid "Acceptable only for single-line, non-embedded statements."
msgstr ""

#: ../../contribute/code.rst:393
msgid "Minimize complexity"
msgstr ""

#: ../../contribute/code.rst:395
msgid "Minimize nested blocks and distinct execution paths through code. Use `Return Early`__ to reduce nesting levels and cognitive load when reading code."
msgstr ""

#: ../../contribute/code.rst:401
msgid "Use comments effectively"
msgstr ""

#: ../../contribute/code.rst:403
msgid "Good comments describe the \"why.\"  Good code describes the \"how.\" E.g.:"
msgstr ""

#: ../../contribute/code.rst:405
#: ../../contribute/code.rst:540
#: ../../contribute/code.rst:576
#: ../../contribute/code.rst:614
#: ../../contribute/code.rst:657
#: ../../contribute/code.rst:677
#: ../../contribute/code.rst:696
#: ../../contribute/code.rst:714
#: ../../contribute/code.rst:736
#: ../../contribute/code.rst:760
msgid "Bad:"
msgstr ""

#: ../../contribute/code.rst:416
#: ../../contribute/code.rst:527
#: ../../contribute/code.rst:556
#: ../../contribute/code.rst:593
#: ../../contribute/code.rst:631
#: ../../contribute/code.rst:667
#: ../../contribute/code.rst:683
#: ../../contribute/code.rst:702
#: ../../contribute/code.rst:722
#: ../../contribute/code.rst:745
#: ../../contribute/code.rst:768
msgid "Good:"
msgstr ""

#: ../../contribute/code.rst:427
msgid "Always include a comment if it's not obvious that something must be done in a certain way. Other developers looking at the code should be discouraged from refactoring in a way that would break the code."
msgstr ""

#: ../../contribute/code.rst:438
msgid "Commit effectively"
msgstr ""

#: ../../contribute/code.rst:440
msgid "Err on the side of `atomic commits`__ which are highly focused on changing one aspect of the system."
msgstr ""

#: ../../contribute/code.rst:441
msgid "Avoid mixing in unrelated changes or extensive whitespace changes. Commits with many changes are scary and make pull requests difficult to review."
msgstr ""

#: ../../contribute/code.rst:443
msgid "Use visual git tools to craft `highly precise and readable diffs`__."
msgstr ""

#: ../../contribute/code.rst:449
msgid "Include tests"
msgstr ""

#: ../../contribute/code.rst:451
msgid "When at all possible :ref:`include unit tests <contribute/code#testing>` for code you add or alter."
msgstr ""

#: ../../contribute/code.rst:454
msgid "Keep bugfixes simple"
msgstr ""

#: ../../contribute/code.rst:456
msgid "Avoid the temptation to refactor code for a bugfix release. Doing so tends to introduce regressions, breaking functionality in what should be a stable release."
msgstr ""

#: ../../contribute/code.rst:460
msgid "PHP guidelines"
msgstr ""

#: ../../contribute/code.rst:462
msgid "These are the required coding standards for Elgg core and all bundled plugins. Plugin developers are strongly encouraged to adopt these standards."
msgstr ""

#: ../../contribute/code.rst:465
msgid "Developers should first read the `PSR-2 Coding Standard Guide`__."
msgstr ""

#: ../../contribute/code.rst:469
msgid "Elgg's standards extend PSR-2, but differ in the following ways:"
msgstr ""

#: ../../contribute/code.rst:471
msgid "Indent using one tab character, not spaces."
msgstr ""

#: ../../contribute/code.rst:472
msgid "Opening braces for classes, methods, and functions must go on the same line."
msgstr ""

#: ../../contribute/code.rst:473
msgid "If a line reaches over 100 characters, consider refactoring (e.g. introduce variables)."
msgstr ""

#: ../../contribute/code.rst:474
msgid "Compliance with `PSR-1`__ is encouraged, but not strictly required."
msgstr ""

#: ../../contribute/code.rst:479
#: ../../contribute/core/move_plugin.rst:124
msgid "Documentation"
msgstr ""

#: ../../contribute/code.rst:481
msgid "Include PHPDoc comments on functions and classes (all methods; declared properties when appropriate), including types and descriptions of all parameters."
msgstr ""

#: ../../contribute/code.rst:485
msgid "In lists of ``@param`` declarations, the beginnings of variable names and descriptions must line up."
msgstr ""

#: ../../contribute/code.rst:488
msgid "Annotate classes, methods, properties, and functions with ``@internal`` unless they are intended for public use, are already of limited visibility, or are within a class already marked as ``@internal``."
msgstr ""

#: ../../contribute/code.rst:492
msgid "Use ``//`` or ``/* */`` when commenting."
msgstr ""

#: ../../contribute/code.rst:494
msgid "Use only ``//`` comments inside function/method bodies."
msgstr ""

#: ../../contribute/code.rst:497
msgid "Naming"
msgstr ""

#: ../../contribute/code.rst:499
msgid "Use underscores to separate words in the names of functions, variables, and properties. Method names are camelCase."
msgstr ""

#: ../../contribute/code.rst:502
msgid "Names of functions for public use must begin with ``elgg_``."
msgstr ""

#: ../../contribute/code.rst:504
msgid "All other function names must begin with ``_elgg_``."
msgstr ""

#: ../../contribute/code.rst:506
msgid "Name globals and constants in ``ALL_CAPS`` (``ACCESS_PUBLIC``, ``$CONFIG``)."
msgstr ""

#: ../../contribute/code.rst:509
msgid "Miscellaneous"
msgstr ""

#: ../../contribute/code.rst:511
msgid "For PHP requirements, see ``composer.json``."
msgstr ""

#: ../../contribute/code.rst:513
msgid "Do not use PHP shortcut tags ``<?`` or ``<%``. It is OK to use ``<?=`` since it is always enabled as of PHP 5.4."
msgstr ""

#: ../../contribute/code.rst:516
msgid "When creating strings with variables:"
msgstr ""

#: ../../contribute/code.rst:518
msgid "use double-quoted strings"
msgstr ""

#: ../../contribute/code.rst:519
msgid "wrap variables with braces only when necessary."
msgstr ""

#: ../../contribute/code.rst:521
msgid "Bad (hard to read, misuse of quotes and {}s):"
msgstr ""

#: ../../contribute/code.rst:533
msgid "Remove trailing whitespace at the end of lines."
msgstr ""

#: ../../contribute/code.rst:536
msgid "Value validation"
msgstr ""

#: ../../contribute/code.rst:538
msgid "When working with user input prepare the input outside of the validation method."
msgstr ""

#: ../../contribute/code.rst:572
msgid "Use exceptions"
msgstr ""

#: ../../contribute/code.rst:574
msgid "Do not be afraid to use exceptions. They are easier to deal with than mixed function output:"
msgstr ""

#: ../../contribute/code.rst:610
msgid "Documenting return values"
msgstr ""

#: ../../contribute/code.rst:612
msgid "Do not use ``@return void`` on methods that return a value or null."
msgstr ""

#: ../../contribute/code.rst:650
msgid "CSS guidelines"
msgstr ""

#: ../../contribute/code.rst:652
msgid "Save the css in files with a ``.css`` extension."
msgstr ""

#: ../../contribute/code.rst:655
msgid "Use shorthand where possible"
msgstr ""

#: ../../contribute/code.rst:675
msgid "Use hyphens, not underscores"
msgstr ""

#: ../../contribute/code.rst:691
msgid "You should prefix your ids and classnames with text that identifies your plugin."
msgstr ""

#: ../../contribute/code.rst:694
msgid "One property per line"
msgstr ""

#: ../../contribute/code.rst:710
msgid "Property declarations"
msgstr ""

#: ../../contribute/code.rst:712
msgid "These should be spaced like so: ``property: value;``"
msgstr ""

#: ../../contribute/code.rst:729
msgid "Vendor prefixes"
msgstr ""

#: ../../contribute/code.rst:731
msgid "Group vendor-prefixes for the same property together"
msgstr ""

#: ../../contribute/code.rst:732
msgid "Longest vendor-prefixed version first"
msgstr ""

#: ../../contribute/code.rst:733
msgid "Always include non-vendor-prefixed version"
msgstr ""

#: ../../contribute/code.rst:734
msgid "Put an extra newline between vendor-prefixed groups and other properties"
msgstr ""

#: ../../contribute/code.rst:758
msgid "Group subproperties"
msgstr ""

#: ../../contribute/code.rst:779
msgid "Javascript guidelines"
msgstr ""

#: ../../contribute/code.rst:781
msgid "Same formatting standards as PHP apply."
msgstr ""

#: ../../contribute/code.rst:783
msgid "All functions should be in the ``elgg`` namespace."
msgstr ""

#: ../../contribute/code.rst:785
msgid "Function expressions should end with a semi-colon."
msgstr ""

#: ../../contribute/code.rst:796
msgid "Deprecating APIs"
msgstr ""

#: ../../contribute/code.rst:798
msgid "Occasionally functions and classes must be deprecated in favor of newer replacements. Since 3rd party plugin authors rely on a consistent API, backward compatibility must be maintained, but will not be maintained indefinitely as plugin authors are expected to properly update their plugins. In order to maintain backward compatibility, deprecated APIs will follow these guidelines:"
msgstr ""

#: ../../contribute/code.rst:805
msgid "Minor version (1.x) that deprecates an API must include a wrapper function/class (or otherwise appropriate means) to maintain backward compatibility, including any bugs in the original function/class. This compatibility layer uses ``elgg_deprecated_notice('...', '1.11')`` to log that the function is deprecated."
msgstr ""

#: ../../contribute/code.rst:811
msgid "The next major revision (2.0) removes the compatibility layer. Any use of the deprecated API should be corrected before this."
msgstr ""

#: ../../contribute/core/index.rst:2
msgid "Core tasks"
msgstr ""

#: ../../contribute/core/index.rst:4
msgid "Certain tasks surrounding Elgg are reserved for the core developer as they require special permissions. The guides below show the workflow for these actions."
msgstr ""

#: ../../contribute/core/move_plugin.rst:2
msgid "Moving a plugin to its own repository"
msgstr ""

#: ../../contribute/core/move_plugin.rst:9
msgid "Plugin extraction steps"
msgstr ""

#: ../../contribute/core/move_plugin.rst:12
msgid "Move the code to its own repository"
msgstr ""

#: ../../contribute/core/move_plugin.rst:14
msgid "Follow the GitHub guide `Splitting a subfolder out into a new repository`_. This will make sure that the commit history is preserved."
msgstr ""

#: ../../contribute/core/move_plugin.rst:18
msgid "Dependencies"
msgstr ""

#: ../../contribute/core/move_plugin.rst:20
msgid "If the plugin has dependencies on any external libraries, make sure these dependencies are managed. For example if a PHP library is required which comes bundled with Elgg core, make sure to add it to the ``composer.json`` of this plugin as you can't rely on Elgg core keeping the library."
msgstr ""

#: ../../contribute/core/move_plugin.rst:25
msgid "Commit the code"
msgstr ""

#: ../../contribute/core/move_plugin.rst:27
msgid "During the GitHub guide a new repository is created for the plugin you're trying to move."
msgstr ""

#: ../../contribute/core/move_plugin.rst:29
msgid "Since an attemp was already made to extract some of the plugins to their own repository maybe the repository already exists."
msgstr ""

#: ../../contribute/core/move_plugin.rst:31
msgid "If the repository didn't exist for the plugin, make sure you create it under the `Elgg organisation`_."
msgstr ""

#: ../../contribute/core/move_plugin.rst:33
msgid "If the repository already exists, the best way to update the code would be by a Pull Request. This will however probably fail because of a difference in how the repository was first created (as discussed in this `GitHub issue`_)."
msgstr ""

#: ../../contribute/core/move_plugin.rst:36
msgid "The initial repositories where created with"
msgstr ""

#: ../../contribute/core/move_plugin.rst:42
msgid "and the guide calls for"
msgstr ""

#: ../../contribute/core/move_plugin.rst:48
msgid "This will leave a difference in the commits which GitHub is unable to resolve. In that case you'll have to force push the changes to the existing Elgg plugin repository."
msgstr ""

#: ../../contribute/core/move_plugin.rst:53
msgid "Since this will override all the history in the plugin repository, make sure you know this is what you want to do."
msgstr ""

#: ../../contribute/core/move_plugin.rst:56
msgid "Packagist"
msgstr ""

#: ../../contribute/core/move_plugin.rst:58
msgid "Make sure the ``composer.json`` of the plugin contains all the relevant information. Here is an example:"
msgstr ""

#: ../../contribute/core/move_plugin.rst:80
msgid "The ``conflict`` rule is there to help prevent the installation of this plugin in an unsupported Elgg version."
msgstr ""

#: ../../contribute/core/move_plugin.rst:82
msgid "Add the repository to `Packagist`_, for the existing repositories this was already done. Make sure `Packagist`_ is updated correctly with all the commits."
msgstr ""

#: ../../contribute/core/move_plugin.rst:86
msgid "Tag a release"
msgstr ""

#: ../../contribute/core/move_plugin.rst:88
msgid "In order for Composer to be able to cache the plugin for faster installation, a release has to be made on the repository. Probably the first version that needs to be tagged is the same version as mentioned in the ``elgg-plugin.php`` or ``composer.json``. After this development can begin, following the `Semver`_ versioning scheme."
msgstr ""

#: ../../contribute/core/move_plugin.rst:93
#: ../../contribute/core/move_plugin.rst:109
#: ../../contribute/i18n.rst:2
msgid "Translations"
msgstr ""

#: ../../contribute/core/move_plugin.rst:95
msgid "If the translations for the plugin need to be managed by `Transifex`_, add the plugin to `Transifex`_."
msgstr ""

#: ../../contribute/core/move_plugin.rst:98
msgid "Elgg core cleanup"
msgstr ""

#: ../../contribute/core/move_plugin.rst:100
msgid "Now that the plugin has been moved to it's own repository, it's time to make a Pull Request on Elgg core to remove the original code."
msgstr ""

#: ../../contribute/core/move_plugin.rst:103
msgid "Remove the plugin"
msgstr ""

#: ../../contribute/core/move_plugin.rst:105
msgid "Delete the ``mod`` folder for the plugin"
msgstr ""

#: ../../contribute/core/move_plugin.rst:106
msgid "Search for the plugin name in core to find any references which also need to be removed (eg. old docs, special tests, etc.)"
msgstr ""

#: ../../contribute/core/move_plugin.rst:111
msgid "Since the plugin no longer is part of Elgg core, make sure the configuration of `Transifex`_ no longer contains the plugin."
msgstr ""

#: ../../contribute/core/move_plugin.rst:114
msgid "Bundled"
msgstr ""

#: ../../contribute/core/move_plugin.rst:116
msgid "If the plugin still comes bundled with the release of a new Elgg version, make sure to add the plugin to the ``composer.json``."
msgstr ""

#: ../../contribute/core/move_plugin.rst:119
msgid "Composer"
msgstr ""

#: ../../contribute/core/move_plugin.rst:121
msgid "Check the core composer dependencies if requirements that were specific for the removed plugin can also be removed in the core dependencies."
msgstr ""

#: ../../contribute/core/move_plugin.rst:126
msgid "Add a mention in the :doc:`/appendix/upgrade-notes` documentation that the plugin was removed from Elgg core."
msgstr ""

#: ../../contribute/core/releases.rst:2
msgid "Release Process Workflow"
msgstr ""

#: ../../contribute/core/releases.rst:4
msgid "Release a new version of Elgg."
msgstr ""

#: ../../contribute/core/releases.rst:6
msgid "This is the process the core team follows for making a new Elgg release. We have published this information in the spirit of openness, and to streamline onboarding of new team members."
msgstr ""

#: ../../contribute/core/releases.rst:15
msgid "Requirements"
msgstr ""

#: ../../contribute/core/releases.rst:17
msgid "SSH access to elgg.org"
msgstr ""

#: ../../contribute/core/releases.rst:18
msgid "Commit access to http://github.com/Elgg/Elgg"
msgstr ""

#: ../../contribute/core/releases.rst:19
msgid "Admin access to https://elgg.org/"
msgstr ""

#: ../../contribute/core/releases.rst:20
msgid "Access to `Twitter account`_"
msgstr ""

#: ../../contribute/core/releases.rst:21
msgid "Node.js and Yarn installed"
msgstr ""

#: ../../contribute/core/releases.rst:22
msgid "Sphinx installed (``easy_install sphinx && easy_install sphinx-intl``)"
msgstr ""

#: ../../contribute/core/releases.rst:23
msgid "Transifex client installed (``easy_install transifex-client``)"
msgstr ""

#: ../../contribute/core/releases.rst:24
msgid "Transifex account with access to Elgg project"
msgstr ""

#: ../../contribute/core/releases.rst:27
msgid "Merge commits up from lower branches"
msgstr ""

#: ../../contribute/core/releases.rst:29
msgid "Determine the LTS branch. We need to merge any new commits there up through the other branches."
msgstr ""

#: ../../contribute/core/releases.rst:32
msgid "For each branch"
msgstr ""

#: ../../contribute/core/releases.rst:34
msgid "Check out the branch, make sure it's up to date, and make a new work branch with the merge. E.g. here we're merging 1.12 commits into 2.0:"
msgstr ""

#: ../../contribute/core/releases.rst:44
msgid "If already up-to-date (no commits to merge), we can stop here for this branch."
msgstr ""

#: ../../contribute/core/releases.rst:46
msgid "If there are conflicts, resolve them, ``git add .``, and ``git merge``."
msgstr ""

#: ../../contribute/core/releases.rst:48
msgid "Make a PR for the branch and wait for automated tests and approval by other dev(s)."
msgstr ""

#: ../../contribute/core/releases.rst:54
msgid "Once merged, we would repeat the process to merge 2.0 commits into 2.1."
msgstr ""

#: ../../contribute/core/releases.rst:57
msgid "Preparation for first new stable minor/major release"
msgstr ""

#: ../../contribute/core/releases.rst:59
msgid "Update the :doc:`/appendix/support` to include the new minor/major release date and fill in the blanks for the previous release."
msgstr ""

#: ../../contribute/core/releases.rst:60
msgid "Update the README.md file badges to point to the correct new release numbers."
msgstr ""

#: ../../contribute/core/releases.rst:63
msgid "Preparation for a new major release"
msgstr ""

#: ../../contribute/core/releases.rst:65
msgid "Change the Transifex configuration to push translations to a different project"
msgstr ""

#: ../../contribute/core/releases.rst:68
msgid "Prepare the release"
msgstr ""

#: ../../contribute/core/releases.rst:71
msgid "Make a PR with translation updates"
msgstr ""

#: ../../contribute/core/releases.rst:73
#: ../../contribute/core/releases.rst:107
msgid "Install the prerequisites:"
msgstr ""

#: ../../contribute/core/releases.rst:79
#: ../../contribute/core/releases.rst:115
msgid "On Windows you need to run these command in a console with admin privileges"
msgstr ""

#: ../../contribute/core/releases.rst:81
msgid "Run the ``languages.php`` script. For example, to pull translations:"
msgstr ""

#: ../../contribute/core/releases.rst:87
msgid "Make a pull request with the new translations and have it merged before the next step."
msgstr ""

#: ../../contribute/core/releases.rst:89
msgid "Next, manually browse to the ``/admin/site_settings`` page and verify it loads. If it does not, a language file from Transifex may have a PHP syntax error. Fix the error and amend your commit with the new file:"
msgstr ""

#: ../../contribute/core/releases.rst:99
msgid "Make the release PR"
msgstr ""

#: ../../contribute/core/releases.rst:101
msgid "Bring your local git clone up to date."
msgstr ""

#: ../../contribute/core/releases.rst:103
msgid "Merge latest commits up from lowest supported branch."
msgstr ""

#: ../../contribute/core/releases.rst:105
msgid "Visit ``https://github.com/Elgg/Elgg/compare/<new>...<old>`` and submit the PR if there is anything that needs to be merged up."
msgstr ""

#: ../../contribute/core/releases.rst:117
msgid "Run the ``release.php`` script. For example, to release 1.12.5:"
msgstr ""

#: ../../contribute/core/releases.rst:124
msgid "This creates a ``release-1.12.5`` branch in your local repo."
msgstr ""

#: ../../contribute/core/releases.rst:126
msgid "Next, submit a pull request via GitHub for automated testing and approval by another developer:"
msgstr ""

#: ../../contribute/core/releases.rst:133
msgid "Tag the release"
msgstr ""

#: ../../contribute/core/releases.rst:135
msgid "Once approved and merged, tag the release:"
msgstr ""

#: ../../contribute/core/releases.rst:143
msgid "Or create a release on GitHub"
msgstr ""

#: ../../contribute/core/releases.rst:145
msgid "Goto releases"
msgstr ""

#: ../../contribute/core/releases.rst:146
msgid "Click 'Draft a new release'"
msgstr ""

#: ../../contribute/core/releases.rst:147
msgid "Enter the version"
msgstr ""

#: ../../contribute/core/releases.rst:148
msgid "Select the correct branch (eg 1.12 for a 1.12.x release, 2.3 for a 2.3.x release, etc)"
msgstr ""

#: ../../contribute/core/releases.rst:149
msgid "Set the release title as 'Elgg {version}'"
msgstr ""

#: ../../contribute/core/releases.rst:150
msgid "Paste the CHANGELOG.md part related to this release in the description"
msgstr ""

#: ../../contribute/core/releases.rst:152
msgid "Some final administration"
msgstr ""

#: ../../contribute/core/releases.rst:154
msgid "Mark GitHub release milestones as completed"
msgstr ""

#: ../../contribute/core/releases.rst:155
msgid "Move unresolved tickets in released milestones to later milestones"
msgstr ""

#: ../../contribute/core/releases.rst:158
msgid "Additional actions for the first new minor / major"
msgstr ""

#: ../../contribute/core/releases.rst:160
msgid "Make a new branch on GitHub (for example 3.3)"
msgstr ""

#: ../../contribute/core/releases.rst:161
msgid "Set the new branch as the default branch (optional, but suggested for stable releases)"
msgstr ""

#: ../../contribute/core/releases.rst:162
msgid "Configure Read The Docs to build the new branch (not the new tag)"
msgstr ""

#: ../../contribute/core/releases.rst:163
msgid "Check the Elgg starter project for potential requirement / config changes in the ``composer.json``"
msgstr ""

#: ../../contribute/core/releases.rst:164
msgid "Add the new minor / major version to the ``Elgg/community_plugins`` repository so developers can upload plugins for the new release"
msgstr ""

#: ../../contribute/core/releases.rst:167
msgid "Additional action for the first new major"
msgstr ""

#: ../../contribute/core/releases.rst:169
msgid "On GitHub add a branch protection rule (for example ``4.*``)"
msgstr ""

#: ../../contribute/core/releases.rst:170
msgid "Configure Scrutinizer to track the new major branches (for example ``4.*``)"
msgstr ""

#: ../../contribute/core/releases.rst:173
msgid "Update the website"
msgstr ""

#: ../../contribute/core/releases.rst:175
msgid "ssh to elgg.org"
msgstr ""

#: ../../contribute/core/releases.rst:176
msgid "Clone https://github.com/Elgg/elgg-scripts"
msgstr ""

#: ../../contribute/core/releases.rst:179
msgid "Build zip package"
msgstr ""

#: ../../contribute/core/releases.rst:181
msgid "Use ``elgg-scripts/build/elgg-starter-project.sh`` to generate the .zip file. Run without arguments to see usage."
msgstr ""

#: ../../contribute/core/releases.rst:196
msgid "For Elgg 2.x releases use the ``2.x`` branch of the starter-project (eg. ``./elgg-starter-project.sh 2.x 2.0.4 /var/www/www.elgg.org/download/``)"
msgstr ""

#: ../../contribute/core/releases.rst:198
msgid "Verify that ``vendor/elgg/elgg/composer.json`` in the zip file has the expected version."
msgstr ""

#: ../../contribute/core/releases.rst:199
msgid "If not, make sure GitHub has the release tag, and that the starter project has a compatible ``elgg/elgg`` item in the composer requires list."
msgstr ""

#: ../../contribute/core/releases.rst:203
msgid "Update elgg.org download page"
msgstr ""

#: ../../contribute/core/releases.rst:205
msgid "Clone https://github.com/Elgg/community"
msgstr ""

#: ../../contribute/core/releases.rst:206
msgid "Add the new version to ``classes/Elgg/Releases.php``"
msgstr ""

#: ../../contribute/core/releases.rst:207
#: ../../contribute/core/releases.rst:225
msgid "Commit and push the changes"
msgstr ""

#: ../../contribute/core/releases.rst:208
msgid "Update the plugin on www.elgg.org"
msgstr ""

#: ../../contribute/core/releases.rst:215
msgid "Update elgg.org"
msgstr ""

#: ../../contribute/core/releases.rst:217
msgid "Clone https://github.com/Elgg/www.elgg.org"
msgstr ""

#: ../../contribute/core/releases.rst:218
msgid "Change the required Elgg version in ``composer.json``"
msgstr ""

#: ../../contribute/core/releases.rst:219
msgid "Update vendors"
msgstr ""

#: ../../contribute/core/releases.rst:226
msgid "Pull to live site"
msgstr ""

#: ../../contribute/core/releases.rst:232
msgid "Update dependencies"
msgstr ""

#: ../../contribute/core/releases.rst:240
msgid "Go to community admin panel"
msgstr ""

#: ../../contribute/core/releases.rst:239
msgid "Flush APC cache"
msgstr ""

#: ../../contribute/core/releases.rst:240
msgid "Run upgrade"
msgstr ""

#: ../../contribute/core/releases.rst:243
msgid "Make the announcement"
msgstr ""

#: ../../contribute/core/releases.rst:245
msgid "This should be the very last thing you do."
msgstr ""

#: ../../contribute/core/releases.rst:247
msgid "Open ``https://github.com/Elgg/Elgg/blob/<tag>/CHANGELOG.md`` and copy the contents for that version"
msgstr ""

#: ../../contribute/core/releases.rst:248
msgid "Sign in at https://elgg.org/blog and compose a new blog with a summary"
msgstr ""

#: ../../contribute/core/releases.rst:249
msgid "Copy in the CHANGELOG contents, clear formatting, and manually remove the SVG anchors"
msgstr ""

#: ../../contribute/core/releases.rst:250
msgid "Add tags ``release`` and ``elgg2.x`` where x is whatever branch is being released"
msgstr ""

#: ../../contribute/core/releases.rst:251
msgid "Tweet from the elgg `Twitter account`_"
msgstr ""

#: ../../contribute/database.rst:2
msgid "Database"
msgstr ""

#: ../../contribute/database.rst:4
msgid "Contributing database schema changes"
msgstr ""

#: ../../contribute/database.rst:11
msgid "Database Migrations"
msgstr ""

#: ../../contribute/database.rst:13
msgid "Elgg uses `Phinx`_ to manage the database migrations."
msgstr ""

#: ../../contribute/database.rst:19
msgid "Create a migration"
msgstr ""

#: ../../contribute/database.rst:21
msgid "To create a new migration run the following in your console:"
msgstr ""

#: ../../contribute/database.rst:28
msgid "This will generate a timestamped skeleton migration in ``engine/schema/migrations/``. Follow Phinx documentation to call the necessary methods to modify the database tables."
msgstr ""

#: ../../contribute/database.rst:34
msgid "Executing a migration"
msgstr ""

#: ../../contribute/database.rst:36
msgid "Migrations are executed every time your run ``upgrade.php``. If you would like to execute migrations manually, you can do so via the command line:"
msgstr ""

#: ../../contribute/database.rst:47
msgid "Check Phinx documentation for additional flags that allow you to run a single migration or a set of migrations within a time range."
msgstr ""

#: ../../contribute/docs.rst:2
msgid "Writing Documentation"
msgstr ""

#: ../../contribute/docs.rst:4
msgid "New documentation should fit well with the rest of Elgg's docs."
msgstr ""

#: ../../contribute/docs.rst:11
msgid "Testing docs locally"
msgstr ""

#: ../../contribute/docs.rst:12
msgid "Elgg has a `grunt`_ script that automatically builds the docs, opens them in a browser window, and automatically reloads as you make changes (the reload takes just a few seconds). You need `yarn`_ and `sphinx`_ installed to be able to use these scripts."
msgstr ""

#: ../../contribute/docs.rst:22
msgid "It's that easy! Grunt will continue running, watching the docs for changes and automatically rebuilding."
msgstr ""

#: ../../contribute/docs.rst:27
msgid "You might need to install 'sphinxcontrib-phpdomain'. You can do this with the following command: `pip install -U sphinxcontrib-phpdomain`"
msgstr ""

#: ../../contribute/docs.rst:35
msgid "Follow the existing document organization"
msgstr ""

#: ../../contribute/docs.rst:36
msgid "The current breakdown is not necessarily the One True Way to organize docs, but consistency is better than randomness."
msgstr ""

#: ../../contribute/docs.rst:41
msgid "intro/*"
msgstr ""

#: ../../contribute/docs.rst:42
msgid "This is everything that brand new users need to know (installation, features, license, etc.)"
msgstr ""

#: ../../contribute/docs.rst:45
msgid "admin/*"
msgstr ""

#: ../../contribute/docs.rst:46
msgid "Guides for administrators. Task-oriented."
msgstr ""

#: ../../contribute/docs.rst:49
msgid "guides/*"
msgstr ""

#: ../../contribute/docs.rst:50
msgid "API guides for plugin developers. Cookbook-style. Example heavy. Code snippet heavy. Broken down by services (actions, i18n, routing, db, etc.). This should only discuss the public API and its behavior, not implementation details or reasoning."
msgstr ""

#: ../../contribute/docs.rst:55
msgid "design/*"
msgstr ""

#: ../../contribute/docs.rst:56
msgid "Design docs for people who want to get a better understanding of how/why core is built the way it is. This should discuss internal implementation details of the various services, what tradeoffs were made, and the reasoning behind the final decision. Should be useful for people who want to contribute and for communication b/w core devs."
msgstr ""

#: ../../contribute/docs.rst:62
msgid "contribute/*"
msgstr ""

#: ../../contribute/docs.rst:63
msgid "Contributors guides for the various ways people can participate in the project."
msgstr ""

#: ../../contribute/docs.rst:66
msgid "appendix/*"
msgstr ""

#: ../../contribute/docs.rst:67
msgid "More detailed/meta/background information about the project (history, roadmap, etc.)"
msgstr ""

#: ../../contribute/docs.rst:71
msgid "Use \"Elgg\" in a grammatically correct way"
msgstr ""

#: ../../contribute/docs.rst:72
msgid "Elgg is not an acronym, so writing it in all caps (ELGG or E-LGG) is incorrect. Please don't do this."
msgstr ""

#: ../../contribute/docs.rst:76
msgid "In English, Elgg does not take an article when used as a noun. Here are some examples to emulate:"
msgstr ""

#: ../../contribute/docs.rst:75
msgid "\"I'm using Elgg to run my website\""
msgstr ""

#: ../../contribute/docs.rst:76
msgid "\"Install Elgg to get your community online\""
msgstr ""

#: ../../contribute/docs.rst:80
msgid "When used as an adjective, the article applies to the main noun, so you should use one. For example:"
msgstr ""

#: ../../contribute/docs.rst:79
msgid "\"Go to the Elgg community website to get help.\""
msgstr ""

#: ../../contribute/docs.rst:80
msgid "\"I built an Elgg-based network yesterday\""
msgstr ""

#: ../../contribute/docs.rst:82
msgid "This advice may not apply in languages other than English."
msgstr ""

#: ../../contribute/docs.rst:86
msgid "Avoid first person pronouns"
msgstr ""

#: ../../contribute/docs.rst:87
msgid "Refer to the reader as \"you\". Do not include yourself in the normal narrative."
msgstr ""

#: ../../contribute/docs.rst:89
#: ../../contribute/docs.rst:100
#: ../../contribute/docs.rst:112
#: ../../contribute/docs.rst:126
msgid "Before:"
msgstr ""

#: ../../contribute/docs.rst:91
msgid "When we're done installing Elgg, we'll look for some plugins!"
msgstr ""

#: ../../contribute/docs.rst:93
#: ../../contribute/docs.rst:104
#: ../../contribute/docs.rst:116
#: ../../contribute/docs.rst:130
msgid "After:"
msgstr ""

#: ../../contribute/docs.rst:95
msgid "When you're done installing Elgg, look for some plugins!"
msgstr ""

#: ../../contribute/docs.rst:97
msgid "To refer to yourself (avoid this if possible), use your name and write in the third person. This clarifies to future readers/editors whose opinions are being expressed."
msgstr ""

#: ../../contribute/docs.rst:102
msgid "I think the best way to do X is to use Y."
msgstr ""

#: ../../contribute/docs.rst:106
msgid "Evan thinks the best way to do X is to use Y."
msgstr ""

#: ../../contribute/docs.rst:110
msgid "Eliminate fluff"
msgstr ""

#: ../../contribute/docs.rst:114
msgid "If you want to use a third-party javascript library within the Elgg framework, you should take care to call the ``elgg_register_external_file`` function to register it."
msgstr ""

#: ../../contribute/docs.rst:118
msgid "To use a third-party javascript library, call ``elgg_register_external_file`` to register it."
msgstr ""

#: ../../contribute/docs.rst:122
msgid "Prefer absolute dates over relative ones"
msgstr ""

#: ../../contribute/docs.rst:123
msgid "It is not easy to tell when a particular sentence or paragraph was written, so relative dates quickly become meaningless. Absolute dates also give the reader a good indication of whether a project has been abandoned, or whether some advice might be out of date."
msgstr ""

#: ../../contribute/docs.rst:128
msgid "Recently the foo was barred. Soon, the baz will be barred too."
msgstr ""

#: ../../contribute/docs.rst:132
msgid "Recently (as of September 2013), the foo was barred. The baz is expected to be barred by October 2013."
msgstr ""

#: ../../contribute/docs.rst:136
msgid "Do not remind the reader to contribute"
msgstr ""

#: ../../contribute/docs.rst:137
msgid "Focus on addressing only the topic at hand. Constant solicitation for free work is annoying and makes the project look needy. If people want to contribute to the project, they can visit the contributor guide."
msgstr ""

#: ../../contribute/docs.rst:143
msgid "Internationalizing documentation"
msgstr ""

#: ../../contribute/docs.rst:145
msgid "When you change documentation, remember to update the documentation translation templates before you commit:"
msgstr ""

#: ../../contribute/docs.rst:153
msgid "For more information, see http://www.sphinx-doc.org/en/stable/intl.html#translating-with-sphinx-intl"
msgstr ""

#: ../../contribute/docs.rst:157
msgid "Special attention"
msgstr ""

#: ../../contribute/docs.rst:159
msgid "When translating the documentation be aware of special syntax in the documentation files."
msgstr ""

#: ../../contribute/docs.rst:162
msgid "Translating links"
msgstr ""

#: ../../contribute/docs.rst:164
msgid "Translate text in anonymous links (e.g., ```pronunciation`__``), but maintain the order of all anonymous links in a single block. If there are two anonymous links within a single block for translation, they must not be rearranged relative to each other."
msgstr ""

#: ../../contribute/docs.rst:165
msgid "Translate the text of named links (e.g., ```demo site`_``) but only if you maintain the name using the correct rST syntax. In this case that would be ```translation of \"demo site\" <demo site_>`_``."
msgstr ""

#: ../../contribute/docs.rst:168
msgid "Do NOT translate"
msgstr ""

#: ../../contribute/docs.rst:170
msgid "Anything between pipe characters should not be translated (e.g., |version|)."
msgstr ""

#: ../../contribute/docs.rst:171
msgid "Code, unless it's a comment in the code."
msgstr ""

#: ../../contribute/i18n.rst:4
msgid "Translations multiply the impact that Elgg can have by making it accessible to a larger percentage of the world."
msgstr ""

#: ../../contribute/i18n.rst:7
msgid "The community will always be indebted to those of you who work hard to provide high quality translations for Elgg's UI and docs."
msgstr ""

#: ../../contribute/i18n.rst:11
msgid "Transifex"
msgstr ""

#: ../../contribute/i18n.rst:13
msgid "All translation for the Elgg project is organized through Transifex."
msgstr ""

#: ../../contribute/i18n.rst:15
msgid "https://www.transifex.com/organization/elgg"
msgstr ""

#: ../../contribute/i18n.rst:17
msgid "Plugin authors are encouraged to coordinate translations via Transifex as well so the whole community can be unified and make it really easy for translators to contribute to any plugin in the Elgg ecosystem."
msgstr ""

#: ../../contribute/i18n.rst:22
msgid "Pulling translations"
msgstr ""

#: ../../contribute/i18n.rst:24
msgid "The translations made in Transifex need to be periodically pulled into the Elgg code repository. This can be done with the script ``.scripts/languages.php`` bundled within Elgg's source code."
msgstr ""

#: ../../contribute/i18n.rst:31
msgid "Prerequisites for running the script are:"
msgstr ""

#: ../../contribute/i18n.rst:29
msgid "Access to command line"
msgstr ""

#: ../../contribute/i18n.rst:30
msgid "`Git`_"
msgstr ""

#: ../../contribute/i18n.rst:31
msgid "`Transifex CLI tool`_"
msgstr ""

#: ../../contribute/i18n.rst:40
msgid "The script will do the following steps:"
msgstr ""

#: ../../contribute/i18n.rst:37
msgid "Create a new git branch named ``{branch}_i18n_{timestamp}``"
msgstr ""

#: ../../contribute/i18n.rst:38
msgid "Pull translations for all languages that have 95% of the strings translated"
msgstr ""

#: ../../contribute/i18n.rst:39
msgid "Remove possible invalid language codes"
msgstr ""

#: ../../contribute/i18n.rst:40
msgid "Commit the changes to the branch"
msgstr ""

#: ../../contribute/i18n.rst:42
msgid "After this you must push the branch to Github and make a new Pull request."
msgstr ""

#: ../../contribute/i18n.rst:44
msgid "For example if you want to pull the translations for the ``3.x`` branch, run the following commands:"
msgstr ""

#: ../../contribute/i18n.rst:52
msgid "Run the command without parameters to get more detailed information of the usage."
msgstr ""

#: ../../contribute/i18n.rst:55
msgid "Transifex configuration"
msgstr ""

#: ../../contribute/i18n.rst:57
msgid "The configuration for Transifex can be found from Elgg's source code in the file ``.tx/config``."
msgstr ""

#: ../../contribute/i18n.rst:62
msgid "This file defines:"
msgstr ""

#: ../../contribute/i18n.rst:61
msgid "The Transifex project associated with Elgg's major version"
msgstr ""

#: ../../contribute/i18n.rst:62
msgid "The location of all the files that have translatable content"
msgstr ""

#: ../../contribute/i18n.rst:64
msgid "Read the `Transifex documentation`_ for further details."
msgstr ""

#: ../../contribute/i18n.rst:69
msgid "New major Elgg version"
msgstr ""

#: ../../contribute/i18n.rst:71
msgid "Every major version of Elgg must have its own project in Transifex. This way we can make sure that strings added and removed between versions do not conflict with each other. For example a translation key removed in Elgg 3 should not get removed from translations made for Elgg 2. Respectfully a new string added only to Elgg 3 should not be included in the translations meant for Elgg 2."
msgstr ""

#: ../../contribute/i18n.rst:77
msgid "The process of setting up a new major version is:"
msgstr ""

#: ../../contribute/i18n.rst:79
msgid "Pull latest translations from Transifex to the previous major version"
msgstr ""

#: ../../contribute/i18n.rst:80
msgid "Merge the git branch of the previous version to the new to make sure all the latest translation keys are present"
msgstr ""

#: ../../contribute/i18n.rst:82
msgid "Create a new Transifex project to https://www.transifex.com/elgg/"
msgstr ""

#: ../../contribute/i18n.rst:83
msgid "Update ``.tx/config`` file in the development branch of the new major version"
msgstr ""

#: ../../contribute/i18n.rst:85
msgid "Update the configuration to point to the new Transifex project"
msgstr ""

#: ../../contribute/i18n.rst:86
msgid "Remove configuration of removed plugins"
msgstr ""

#: ../../contribute/i18n.rst:87
msgid "Add configuration for new plugins"
msgstr ""

#: ../../contribute/i18n.rst:89
msgid "Push the translation sources to the new Transifex project with the command: ::"
msgstr ""

#: ../../contribute/i18n.rst:94
msgid "Copy the new configuration file temporarily (do not commit) to the previous major version, and push the existing translations from it to the new project: ::"
msgstr ""

#: ../../contribute/i18n.rst:100
msgid "Later, once the dedicated branch (e.g. ``3.x`` has been created for the major version, configure Transifex to fetch new translation keys from it automatically in https://www.transifex.com/elgg/elgg-core-3/content/. This way you don't have to repeat step 5 manually every time new translation keys are added."
msgstr ""

#: ../../contribute/i18n.rst:105
msgid "It is important to always have a ``n.x`` branch besides the branches meant for specific minor versions (``n.1``, ``n.2``, etc.). This way the URLs of the auto-update sources do not have to be updated every time a new minor branch is created."
msgstr ""

#: ../../contribute/index.rst:2
msgid "Contributor Guides"
msgstr ""

#: ../../contribute/index.rst:4
msgid "Participate in making Elgg even better."
msgstr ""

#: ../../contribute/index.rst:6
msgid "Elgg is a community-driven project. It relies on the support of volunteers to succeed. Here are some ways you can help:"
msgstr ""

#: ../../contribute/issues.rst:2
msgid "Reporting Issues"
msgstr ""

#: ../../contribute/issues.rst:4
msgid "Report bugs and features requests to https://github.com/Elgg/Elgg/issues. See below for guidelines."
msgstr ""

#: ../../contribute/issues.rst:8
msgid "DISCLAIMERS"
msgstr ""

#: ../../contribute/issues.rst:12
msgid "Security issues should be reported to **security @ elgg . org**! Please do not post any security issues on github!!"
msgstr ""

#: ../../contribute/issues.rst:16
msgid "Support requests belong on the `community site`_. Tickets with support requests will be closed."
msgstr ""

#: ../../contribute/issues.rst:20
msgid "We cannot make any guarantees as to when your ticket will be resolved."
msgstr ""

#: ../../contribute/issues.rst:23
msgid "Bug reports"
msgstr ""

#: ../../contribute/issues.rst:25
msgid "Before submitting a bug report:"
msgstr ""

#: ../../contribute/issues.rst:27
msgid "Search for an existing ticket on the issue you’re having. Add any extra info there."
msgstr ""

#: ../../contribute/issues.rst:29
msgid "Verify the problem is reproducible"
msgstr ""

#: ../../contribute/issues.rst:31
msgid "On the latest version of Elgg"
msgstr ""

#: ../../contribute/issues.rst:32
msgid "With all third-party plugins disabled"
msgstr ""

#: ../../contribute/issues.rst:34
msgid "Good bug report checklist:"
msgstr ""

#: ../../contribute/issues.rst:36
msgid "Expected behavior and actual behavior"
msgstr ""

#: ../../contribute/issues.rst:37
msgid "Clear steps to reproduce the problem"
msgstr ""

#: ../../contribute/issues.rst:38
msgid "The version of Elgg you’re running"
msgstr ""

#: ../../contribute/issues.rst:39
msgid "Browsers affected by this problem"
msgstr ""

#: ../../contribute/issues.rst:42
msgid "Feature requests"
msgstr ""

#: ../../contribute/issues.rst:44
msgid "Before submitting a feature request:"
msgstr ""

#: ../../contribute/issues.rst:46
msgid "Check the `community site`_ for a plugin that has the features you need."
msgstr ""

#: ../../contribute/issues.rst:48
msgid "Consider if you can :doc:`develop a plugin </tutorials/index>` that does what you need."
msgstr ""

#: ../../contribute/issues.rst:49
msgid "Search through the closed tickets to see if someone else suggested the same feature, but got turned down. You’ll need to be able to explain why your suggestion should be considered this time."
msgstr ""

#: ../../contribute/issues.rst:53
msgid "Good feature request checklist:"
msgstr ""

#: ../../contribute/issues.rst:55
msgid "Detailed explanation of the feature"
msgstr ""

#: ../../contribute/issues.rst:56
msgid "Real-life use-cases"
msgstr ""

#: ../../contribute/issues.rst:57
msgid "Proposed API"
msgstr ""

#: ../../contribute/money.rst:2
msgid "Becoming a Financial Supporter"
msgstr ""

#: ../../contribute/money.rst:6
msgid "All funds raised via the Elgg supporters network go directly into:"
msgstr ""

#: ../../contribute/money.rst:5
msgid "Elgg core development"
msgstr ""

#: ../../contribute/money.rst:6
msgid "Infrastructure provision (elgg.org, github, etc.)"
msgstr ""

#: ../../contribute/money.rst:8
msgid "It is a great way to help with Elgg development!"
msgstr ""

#: ../../contribute/money.rst:11
msgid "Benefits"
msgstr ""

#: ../../contribute/money.rst:12
msgid "For only $50 per year for individuals or $150 per year for organizations, you can get listed as a supporter on `our supporters page`_. Elgg supporters are listed there unless they request not to be."
msgstr ""

#: ../../contribute/money.rst:18
msgid "Supporters are able to put this official logo on their site if they wish:"
msgstr ""

#: ../../contribute/money.rst:25
msgid "Disclaimer"
msgstr ""

#: ../../contribute/money.rst:26
msgid "We operate a no refund policy on supporter subscriptions. If you would like to withdraw your support, go to PayPal and cancel your subscription. You will not be billed the following year."
msgstr ""

#: ../../contribute/money.rst:30
msgid "Being an Elgg Supporter does not give an individual or organization the right to impersonate, trade as or imply they are connected to the Elgg project. They can, however, mention that they support the Elgg project."
msgstr ""

#: ../../contribute/money.rst:34
msgid "If you have any questions about this disclaimer, email info@elgg.org."
msgstr ""

#: ../../contribute/money.rst:36
msgid "We reserve the right to remove or refuse a listing without any prior warning at our complete discretion. There is no refund policy."
msgstr ""

#: ../../contribute/money.rst:39
msgid "If there is no obvious use of Elgg, your site will be linked to with \"nofollow\" set."
msgstr ""

#: ../../contribute/money.rst:42
msgid "Sign up"
msgstr ""

#: ../../contribute/money.rst:43
msgid "If you would like to become an Elgg supporter:"
msgstr ""

#: ../../contribute/money.rst:45
msgid "read the disclaimer_ above"
msgstr ""

#: ../../contribute/money.rst:46
msgid "on the supporters page, `subscribe via PayPal`__"
msgstr ""

#: ../../contribute/money.rst:47
msgid "send an email to info@elgg.org with:"
msgstr ""

#: ../../contribute/money.rst:49
msgid "the date you subscribed"
msgstr ""

#: ../../contribute/money.rst:50
msgid "your name (and organization name, if applicable)"
msgstr ""

#: ../../contribute/money.rst:51
msgid "your website"
msgstr ""

#: ../../contribute/money.rst:52
msgid "your Elgg community profile"
msgstr ""

#: ../../contribute/money.rst:57
msgid "Once all the details have been received, we will add you to the appropriate list. Thanks for your support!"
msgstr ""

#: ../../contribute/services.rst:2
msgid "Adding a Service to Elgg"
msgstr ""

#: ../../contribute/services.rst:4
msgid "The :doc:`services guide </guides/services>` has general information about using Elgg services."
msgstr ""

#: ../../contribute/services.rst:6
msgid "To add a new service object to Elgg:"
msgstr ""

#: ../../contribute/services.rst:8
msgid "Annotate your class as ``@internal``."
msgstr ""

#: ../../contribute/services.rst:9
msgid "Open the class ``Elgg\\Di\\ServiceProvider``."
msgstr ""

#: ../../contribute/services.rst:10
msgid "Add a ``@property-read`` annotation for your service at the top. This allows IDEs and static code analyzers to understand the type of the property."
msgstr ""

#: ../../contribute/services.rst:12
msgid "To the constructor, add code to tell the service provider what to return. See the class ``Elgg\\Di\\DiContainer`` for more information on how Elgg's DI container works."
msgstr ""

#: ../../contribute/services.rst:15
msgid "At this point your service will be available from the service provider object, but will not yet be accessible to plugins."
msgstr ""

#: ../../contribute/services.rst:18
msgid "Inject your dependencies"
msgstr ""

#: ../../contribute/services.rst:20
msgid "Design your class constructor to *ask for* the necessary dependencies rather than creating them or using ``_elgg_services()``. The service provider's ``setFactory()`` method provides access to the service provider instance in your factory method."
msgstr ""

#: ../../contribute/services.rst:24
msgid "Here's an example of a ``foo`` service factory, injecting the ``config`` and ``db`` services into the constructor:"
msgstr ""

#: ../../contribute/services.rst:34
msgid "The full list of internal services can be seen in the ``@property-read`` declarations at the top of ``Elgg\\Di\\ServiceProvider``."
msgstr ""

#: ../../contribute/services.rst:39
msgid "Avoid performing work in your service constructor, particularly if it requires database queries. Currently PHPUnit tests cannot perform them."
msgstr ""

#: ../../contribute/services.rst:44
msgid "Making a service part of the public API"
msgstr ""

#: ../../contribute/services.rst:46
msgid "If your service is meant for use by plugin developers:"
msgstr ""

#: ../../contribute/services.rst:48
msgid "Make an interface ``Elgg\\Services\\<Name>`` that contains only those methods needed in the public API."
msgstr ""

#: ../../contribute/services.rst:49
msgid "Have your service class implement that interface."
msgstr ""

#: ../../contribute/services.rst:50
msgid "For methods that are in the interface, move the documentation to the interface. You can simply use ``{@inheritdoc}`` in the PHPDocs of the concrete class methods."
msgstr ""

#: ../../contribute/services.rst:52
msgid "Document your service in ``docs/guides/services.rst`` (this file)."
msgstr ""

#: ../../contribute/services.rst:53
msgid "Open the PHPUnit test ``Elgg\\ApplicationTest`` and add your service key to the ``$names`` array in ``testServices()``."
msgstr ""

#: ../../contribute/services.rst:55
msgid "Open the class ``Elgg\\Application``."
msgstr ""

#: ../../contribute/services.rst:56
msgid "Add ``@property-read`` declaration to document your service, but use your **interface** as the type, *not* your service class name."
msgstr ""

#: ../../contribute/services.rst:58
msgid "Add your service key to the array in the ``$public_services`` property, e.g. ``'foo' => true,``"
msgstr ""

#: ../../contribute/services.rst:60
msgid "Now your service will be available via property access on the ``Elgg\\Application`` instance:"
msgstr ""

#: ../../contribute/services.rst:69
msgid "For examples, see the ``config`` service, including the interface ``Elgg\\Services\\Config`` and the concrete implementation ``Elgg\\Config``."
msgstr ""

#: ../../contribute/services.rst:73
msgid "Service Life Cycle and Factories"
msgstr ""

#: ../../contribute/services.rst:75
msgid "By default, services registered on the service provider are \"shared\", meaning the service provider will store the created instance for the rest of the request, and serve that same instance to all who request the property."
msgstr ""

#: ../../contribute/services.rst:79
msgid "If you need developers to be able to construct objects that are pre-wired to Elgg services, you may need to add a public factory method to ``Elgg\\Application``. Here's an example that returns a new instance using internal Elgg services:"
msgstr ""

#: ../../contribute/tests.rst:2
msgid "Writing tests"
msgstr ""

#: ../../contribute/tests.rst:9
msgid "Vision"
msgstr ""

#: ../../contribute/tests.rst:11
msgid "We want to *make manual testing unnecessary* for core developers, plugin authors, and site administrators by promoting and enabling fast, automated testing at every level of the Elgg stack."
msgstr ""

#: ../../contribute/tests.rst:14
msgid "We look forward to a world where the core developers do not need to do any manual testing to verify the correctness of code contributed to Elgg. Similarly, we envision a world where site administrators can upgrade and install new plugins with confidence that everything works well together."
msgstr ""

#: ../../contribute/tests.rst:18
msgid "Running Tests"
msgstr ""

#: ../../contribute/tests.rst:21
msgid "Elgg Core Test Suite"
msgstr ""

#: ../../contribute/tests.rst:24
msgid "Currently our tests are split in two pieces:"
msgstr ""

#: ../../contribute/tests.rst:24
msgid "PHPUnit tests are located in ``/tests/phpunit`` -- these are split between unit tests and integration tests."
msgstr ""

#: ../../contribute/tests.rst:26
msgid "Since we have a ``phpunit.xml`` configuration at the root of Elgg, testing should be as easy as:"
msgstr ""

#: ../../contribute/tests.rst:35
msgid "Plugin tests"
msgstr ""

#: ../../contribute/tests.rst:37
msgid "Ideally plugins are configured in such a way that they can be unit-tested much like Elgg core. Plugin developers are free to implement their own methods for unit testing, but we encourage everyone to make it as easy as Elgg core:"
msgstr ""

#: ../../contribute/tests.rst:47
msgid "End-to-end tests"
msgstr ""

#: ../../contribute/tests.rst:49
msgid "Since Elgg plugins have so much power to override, filter, and modify Elgg's and other plugins' behavior, it's important to be able to run end-to-end tests on a staging server with your final configuration before deploying to production."
msgstr ""

#: ../../contribute/tests.rst:54
msgid "ToDo: Make it easy to run all Elgg integration and acceptance tests from the admin area given the current plugin configuration. (without worrying about database corruption!)"
msgstr ""

#: ../../contribute/tests.rst:58
msgid "Motivation"
msgstr ""

#: ../../contribute/tests.rst:63
msgid "Briefly, the wins we expect from testing are:"
msgstr ""

#: ../../contribute/tests.rst:61
msgid "Increased confidence in the system."
msgstr ""

#: ../../contribute/tests.rst:62
msgid "More freedom to refactor."
msgstr ""

#: ../../contribute/tests.rst:63
msgid "Built-in, up-to-date documentation."
msgstr ""

#: ../../contribute/tests.rst:65
msgid "We love community contributions, but in order to maintain stability we cannot accept outside contributions without first verifying their correctness. By promoting automated testing, the core developers can avoid the hassle of manual verification before accepting patches. It also means that external developers don't have to spend time earning trust with the core team. If a patch comes in and has tests to verify it, then we can be confident it works without worrying about the reputation of the contributor."
msgstr ""

#: ../../contribute/tests.rst:70
msgid "Note that these benefits can also extend to the plugins repository. Site owners are encouraged to \"test plugins thoroughly\" before deploying them on a production site. As of March 2013, this translates to manually verifying all the features that the plugin promises to offer. But Elgg provides a huge number of features, and it's not reasonable to test for *all* of them on *every browser* you want to support on *every device* you want to support. But what if plugin developers could write tests for their plugins and site owners could just run the tests for all installed plugins to verify the functionality is maintained? Then they wouldn't be limited to just picking plugins from \"trusted\" developers or \"stable\" releases. They could see that, indeed, nothing broke when they upgraded that critical plugin from 1.3 to 2.5, and push the upgrade to production with confidence."
msgstr ""

#: ../../contribute/tests.rst:78
msgid "The reason this isn't happening today is because Elgg itself is not easily testable at this level yet. We want to change that."
msgstr ""

#: ../../contribute/tests.rst:81
msgid "Strategy"
msgstr ""

#: ../../contribute/tests.rst:83
msgid "We have several guiding principles that we think will be helpful in bringing our vision into reality."
msgstr ""

#: ../../contribute/tests.rst:88
msgid "In short, we are advocating:"
msgstr ""

#: ../../contribute/tests.rst:86
msgid "Continuous integration -- if GitHub checks aren't happy, we're not happy"
msgstr ""

#: ../../contribute/tests.rst:87
msgid "Dependency injection -- For creating highly testable, modular code"
msgstr ""

#: ../../contribute/tests.rst:88
msgid "BDD -- Tests should verify features and provide documentation, not rehash the Class API"
msgstr ""

#: ../../contribute/tests.rst:91
msgid "Continuous Integration"
msgstr ""

#: ../../contribute/tests.rst:93
msgid "We run all of our tests on GitHub Actions so that we can get real time feedback on the correctness of incoming pull requests and development as it progresses. **If the GitHub checks aren't passing, we don't commit to the repo.** This empowers us to merge pull requests in at a rapid pace, so long as they pass the tests. It also allows us to reject pull requests without detailed investigation if they do not pass the tests. We can get past the \"does it work or not\" question and talk about the things that humans need to talk about: API design, usefulness to the project, whether it belongs in core or a plugin, etc. We want as many features as possible provided by Elgg core to be verified automatically by tests running on GitHub Actions."
msgstr ""

#: ../../contribute/tests.rst:100
msgid "Dependency Injection"
msgstr ""

#: ../../contribute/tests.rst:102
msgid "In order to maximize testability, **all dependencies need to be explicit**. Global functions, Singletons, and service locators are death for testability because it's impossible to tell what dependencies are hiding under the covers, and it's even harder to mock out those dependencies. Mocking is critical because you want your unit tests to test only one class at a time. Test failures in a TestCase should not result due to brokenness in a dependency; test failures should only indicate brokenness in the class under test. This makes everything much easier to debug. As of March 2013, most of Elgg still assumes and uses global state, and that has made Elgg and Elgg plugins historically very difficult to test. Fortunately we are moving in the opposite direction now, and a lot of work in Elgg 1.9 has gone into refactoring core components to be more dependency injectable. We are already reaping the benefits from that effort."
msgstr ""

#: ../../contribute/tests.rst:111
msgid "Behavior-Driven Development"
msgstr ""

#: ../../contribute/tests.rst:113
msgid "For us this means **we name tests for features rather than methods**. When you test for features, you are encouraged to write fewer, smaller, logical tests. When a test fails, we can know exactly what feature is compromised. Furthermore, when naming your tests for features, the list of tests provides documentation on what features the system supports. Documentation is something that is typically very troublesome to keep up to date, but when documentation and verification are one and the same, it becomes very easy to keep the documentation up to date."
msgstr ""

#: ../../contribute/tests.rst:120
msgid "Consider these two test methods:"
msgstr ""

#: ../../contribute/tests.rst:119
msgid "``testRegister()``"
msgstr ""

#: ../../contribute/tests.rst:120
msgid "``testCanRegisterFilesAsActionHandlers()``"
msgstr ""

#: ../../contribute/tests.rst:122
msgid "From just looking at the names, ``testRegister`` tells you that the class under test probably has a method named register. If this test passes, it presumably verifies that it is behaving correctly, but doesn't tell you what correct behavior entails, or what the original author of the test was intending to verify. If that method has multiple correct uses that you need to test for, this terse naming convention also encourages you to write a very long test which tests for all conditions and features of said method. Test failure could be caused by any one of those uses being compromised, and it will take more time to figure out where the true problem lies."
msgstr ""

#: ../../contribute/tests.rst:128
msgid "On the other hand, ``testCanRegisterFilesAsActionHandlers`` tells you that there are these things called \"actions\" that need to be \"handled\" and that files can be registered as valid handlers for actions. This introduces newcomers to project terminology and communicates clearly the intent of the test to those already familiar with the terminology."
msgstr ""

#: ../../contribute/tests.rst:132
msgid "For a good example of what we're looking for, check out ``/tests/phpunit/Elgg/ViewServiceTest.php``"
msgstr ""

