From c0bdd1a493416936a4d93ff56fbacefa7a80c24e Mon Sep 17 00:00:00 2001 From: Sam Wilson Date: Wed, 12 Jul 2017 11:31:07 +0800 Subject: [PATCH] Add development docs from Wikitech I've tried to pull in all the non-WMF-specific documentation from https://wikitech.wikimedia.org/wiki/Tool:XTools and add it here. There's still more to do, but there always is. :-) --- docs/development.rst | 65 +++++++++++++++++++++++++++--------- docs/pre-requisites.rst | 2 ++ docs/tools/index.rst | 1 + docs/tools/simplecounter.rst | 10 ++++++ 4 files changed, 63 insertions(+), 15 deletions(-) create mode 100644 docs/tools/simplecounter.rst diff --git a/docs/development.rst b/docs/development.rst index b2c37a577..fe8912306 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -5,34 +5,50 @@ Development To contribute to the development of XTools, you may fork us on GitHub. A few things to be aware of first: 1. XTools is based on Symfony 3. We use Twig as our template engine. Symfony is a full MVC system. - a. The controllers are located at ``src/AppBundle/controller``. They are sorted by tool + a. The controllers are located at ``src/AppBundle/controller``. They are sorted by tool. b. The twig templates are located at ``app/resources/views``. They are sorted by tool. 2. We use the ``@Route`` syntax to configure routes. 3. Every tool requires a twig directory and one controller. Also, core parts of XTools require the tool to be registered within `app/config/tools.yml`. Style Guidelines ----------------- +================ -- It's called "XTools" (with two capital letters). -- We use 4 spaces to indent code. -- Opening and closing curly braces must be on their own lines. -- Variable names are camelCase. Constants are ALL_CAPS_AND_UNDERSCORES. Function names are camelCase. +- It's called "XTools", with two capital letters. +- XTools conforms to `PSR2`_ coding standards; use ``./vendor/bin/phpcs`` to check your code. - Functions and routes must begin with the tool name. +- Version numbers follow `Semantic Versioning guidelines`_. + +.. _PSR2: http://www.php-fig.org/psr/psr-2/ +.. _Semantic Versioning guidelines: http://semver.org/ Running Development server --------------------------- +========================== + +First make sure you meet the :ref:`pre-requisites`, and then follow these steps: -Follow these steps +1. Clone the repository: ``git clone https://github.com/x-tools/xtools-rebirth.git && cd xtools-rebirth`` +2. Run ``composer install`` and answer all the prompts. +3. Create a new local database: ``./bin/console doctrine:database:create`` (or ``d:d:c``). +4. Run the database migrations: ``./bin/console doctrine:migrations:migrate`` (or ``d:m:m``) +5. Launch PHP's built-in server: ``./bin/console server:run`` (or ``s:r``). +6. Visit ``http://localhost:8000`` in your web browser. +7. You can stop the server with ``./bin/console server:stop`` (or ``s:s``) -1. Download the repository. -2. Run ``composer install`` -3. Issue ``php bin/console server:run``. -4. Visit ``http://localhost:8000`` in your web browser. +The :ref:`simplecounter` is the simplest tool and should work as soon as you set up XTools. +Test it by going to http://localhost:8000/sc and put in ``Jimbo Wales`` as the Username and ``en.wikipedia.org`` as the Wiki. +After submitting you should quickly get results. -The development server does not cache data. Any changes you make are visible after refreshing the page. +The development server does not cache data; any changes you make are visible after refreshing the page. +When you edit the ``app/config/parameters.yml`` file, you'll need to clear the cache with ``./bin/console c:c``. + +Assets can be dumped with ``./bin/console assetic:dump``, +and if you're actively editing them you can continually watch for changes with ``./bin/console assetic:watch``. + +The logs are in ``var/logs/dev.log``. +If things are acting up unexpectedly, you might try clearing the cache or restarting the server. Developing against WMF databases --------------------------------- +================================ If you want to use the WMF database replicas, open two tunnels with:: @@ -52,7 +68,26 @@ And set the following in ``app/config/parameters.yml``:: database_toolsdb_port: 4712 database_toolsdb_name: toollabs_p -(Change the ``your-*-here`` bits to your own values.) +(Change the ``your-*-here`` bits to your own values, +which you can find in your ``replica.my.cnf`` file on `Tool Labs`_.) + +.. _Tool Labs: https://wikitech.wikimedia.org/wiki/Help:Tool_Labs/Database + +Table mappings +============== + +Tool Labs has different versions of tables that utilize indexing to improve performance. We'll want to take advantage of that. + +* Go to the config directory with ``cd app/config`` +* Create the file table_map.yml from the template: ``cp table_map.yml.dist table_map.yml`` +* Set the contents of the file to the following:: + + parameters: + app.table.archive: 'archive_userindex' + app.table.revision: 'revision_userindex' + app.table.logging: 'logging_logindex' + +Sometimes we want logging_userindex and not the logindex. This is handled in the code via the getTableName() function in [https://github.com/x-tools/xtools-rebirth/blob/master/src/Xtools/Repository.php#L144 Repository.php]. Caching ======= diff --git a/docs/pre-requisites.rst b/docs/pre-requisites.rst index 26f1537ad..c9e1cb52a 100644 --- a/docs/pre-requisites.rst +++ b/docs/pre-requisites.rst @@ -1,3 +1,5 @@ +.. _pre-requisites: + ############## Pre-requisites ############## diff --git a/docs/tools/index.rst b/docs/tools/index.rst index 8f171d956..8a32bacef 100644 --- a/docs/tools/index.rst +++ b/docs/tools/index.rst @@ -6,3 +6,4 @@ Tools editcounter topedits + simplecounter diff --git a/docs/tools/simplecounter.rst b/docs/tools/simplecounter.rst new file mode 100644 index 000000000..2f9587a94 --- /dev/null +++ b/docs/tools/simplecounter.rst @@ -0,0 +1,10 @@ +.. _simplecounter: + +************** +Simple Counter +************** + +The Simple Counter is a quicker way than :ref:`editcounter` to get a brief overview of a user's contributions. + +It displays a user's total number of edits (live, deleted, and a grand-total), +as well as their username, ID, and group membership.