User:Freddy2001/Manual:Huggle

Introduction to Huggle
Welcome to Huggle! We hope you enjoy using our software.

What is Huggle?
Huggle is a fast diff browser application intended for dealing with vandalism or other unconstructive edits on Wikimedia projects, written in C++. It was originally developed in .NET by Gurch, who is no longer active on this project. Anyone can download Huggle, but rollback permission is required to use it in unrestricted mode on English Wikipedia.

Huggle is able to load and review edits made to Wikipedia in real time, helps users identify unconstructive edits, and allows them to be reverted quickly. Various mechanisms are used to draw conclusions to whether an edit is constructive or not. It uses a semi-distributed model where edits are retrieved using a "provider" (this can be anything that is capable of distributing a stream of edit information, such as the Wikipedia API or IRC recent changes feed), pre-parsed and analyzed. This information is then shared with other anti-vandalism tools, such as ClueBot NG. Huggle also uses a number of self-learning mechanisms, including a global white-list (users that are considered trusted) and user-badness scores that are stored locally on the client's computer.

How does it work?
Huggle is connected to mediawiki through API and retrieves a list of edits that are made to a wiki in real time. These edits are then evaluated and moved to queue from which user can open them.

If edit contains some problems, it can be easily reverted, usually by a shortcut such as Q (by default this revert and warn the user who made the edit).

What are the system requirements for using Huggle?
Huggle 3 supports OSX, Linux and Windows directly. Huggle 2 only works on Windows XP, Windows Vista, and Windows 7, but there is also conditional support available for Huggle 2 via Wine on OS X and Linux (more information).

Installing Huggle
Huggle is very easy to install.


 * Step 1: (required on some wikis only) Go to Special:MyPage/huggle.css on a project where you want to use Huggle (project needs to have Huggle installed, in case you need to enable it there, please contact developers in ), insert enable:true onto the first line. This enables Huggle to run on your user account.


 * Step 2: Go to the download page and download the latest stable version for your OS.


 * Step 3: Follow instructions on download page in order to install huggle

That's it! Huggle should be fully operational.

Windows
Huggle is distributed in 3 flavors for windows:


 * MSVC-32: Windows Vista and newer 32 bit CPU
 * MSVC-64: Windows Vista and newer 64 bit CPU
 * MinGW-32: All windows versions 32 bit CPU, may run slower than MSVC version

If you are switching between MinGW and MSVC versions, you may need to purge your current huggle (uninstall and delete all leftovers from Program Files) prior installation of huggle.

Mac OS
Download .dmg file from download page, open it and copy huggle to Applications folder. Huggle should appear in dashboard immediately.

Debian
In a terminal window with superuser privileges (su or sudo) copy and paste as a single line.

To start type:

Uninstalling Huggle
To uninstall Huggle, follow these instructions. If you want to remove all of your configuration options, blank Special:Mypage/huggle.css

Windows
There should be shortcut to "uninstall huggle", using that will uninstall huggle.

There may be some leftovers in program files (folder huggle) which can be deleted.

Your personal configuration is in AppData/Local/Wikimedia/Huggle and can be also deleted if you want.

Mac OS
Just delete huggle from your applications, personal configuration is in ~/Library/Application Support/Wikimedia/Huggle

Debian / Ubuntu
You can safely remove huggle using package manager.

Compiled
When you ran "make install" file called install_manifest was generated in current folder.

It contains location of all files there were installed.

By removing these files you will uninstall huggle.

See http://www.cmake.org/Wiki/CMake_FAQ#Can_I_do_.22make_uninstall.22_with_CMake.3F for more information.

Installing huggle on custom MediaWiki installation
Huggle3 can be used with any mediawiki installation, however keep in mind that it was originally created for WMF wikis, which can be considered a large wiki farm.

For this reason huggle is designed mostly for large wiki farms and in order to run it on single small wiki, you may need to slightly tweak it.

This guide is covering installation to any wiki.

Huggle home
There is a special folder in huggle which is called huggle home.

This folder is displayed by huggle in logs when it starts, for example:

Wed Feb 11 10:01:47 2015  Home: /home/petanb/.local/share/data/Wikimedia/Huggle/

This folder contains all configuration files of huggle and we will refer to it as huggle home or $huggle_home in this manual.

It is possible to have multiple homes in order to create a number of separate huggle installations that are running isolated from each other by passing argument --chroot.

If you want to use huggle with WMF wikis and your own wiki farm, it is recommended to create 2 homes for it.

If you only want to use huggle for 1 wiki farm, you can ignore this.

Global wiki
Since huggle is designed to run on wiki farms, it requires 1 wiki that is called "global wiki" this wiki contains global configuration file that has the information about individual wikis.

In case you have only 1 wiki, you will need to make it a global wiki as well, so that you will have both global and local configuration file there.

Configuration files
 See 

Huggle is using 4 configuration files in following order:


 * $huggle_home/Configuration/huggle3.xml Local configuration on pc where it is installed - this file contains URL of global wiki
 * Huggle/Config Global configuration on global wiki which contains information about local wikis
 * Project:Huggle/Config Local configuration on wiki to which you login
 * User:$NAME/huggle3.css User configuration on local wiki

Step by step deployment on 3rd wiki farm
In this scenario we have a wiki farm with 4 wikis on domains:


 * meta.testfarm.wmflabs.org
 * wiki1.testfarm.wmflabs.org
 * wiki2.testfarm.wmflabs.org
 * wiki3.testfarm.wmflabs.org

On meta.testfarm.wmflabs.org/wiki/Huggle/Configuration we need to have following content:

enable-all:true

version:3.1.0 min-version:3.1.0

config:Project:Huggle/Config documentation:https://www.mediawiki.org/wiki/Manual:Huggle feedback:https://en.wikipedia.org/wiki/Wikipedia:Huggle/Feedback // Only if you have irc recent change stream for your wikis - this is optional // irc-server:irc.wikimedia.org // irc-server-name:irc.wikimedia.org

user-agent:Huggle/$1 http://en.wikipedia.org/wiki/Wikipedia:Huggle user-config:Special:Mypage/huggle.css user-config-hg3:Special:Mypage/huggle3.css

// URL of your whitelist server, if you don't have any, keep this commented out // whitelist-server:http://huggle.wmflabs.org/data/

In Project:Huggle/List put

Important xmlrcs_name is name of your wiki as seen by XmlRcs provider, if you don't have this provider, you can remove it from XML entry. Same applies for wl (whitelist id).

Now on each of these 3 wikis, you put this in Project:Huggle/Config.yaml

Now all you need is update the huggle local configuration, open $huggle_home/Configuration/huggle3.xml and change



to



Now you can start huggle and hit reload button. It should load a list of local wikis. Since now you should be able to use huggle on your wikis.

Note: If your wiki doesn't support HTTPS you must not check it on login form

Startup


When you first start Huggle, you should see a login screen.

At this login screen, you can select the project that you want to log on to from the drop down list.

You can also select a language other than English for Huggle to use for text prompts and buttons.

Enter your project username and password.

Huggle will then log you in, check that your account is able to use it, and read various data pages.

It is also possible to login to multiple projects within a single session.

You can do so by clicking on the Projects button, which would show a list of available projects.


 * Language — The language that objects inside Huggle will be displayed in
 * Project — Drop down list that contains all of the projects that Huggle can work with
 * Username — Your project username
 * Password — Your project password


 *  Require SSL - Force Huggle to use a secure connection to connect to the wiki.

Interface
This is Huggle's interface.



Menu toolbar
Each menu along the top has a specific function.

View details about each menu:



System menu
This is the system menu:




 * Options shows the Huggle options.


 * Reconnect IRC feed allows you to attempt to reconnect to the recent changes IRC feed. This feature is useful if changes aren't showing up.


 * My talk page (M) will display a last revision of your talk page, useful for checking of new messages.


 * Abort (ESC) kills the last query on a stack, this option may not work if you didn't enable delayed reverts.


 * Change Provider let you change the provider of edits to a different one (wiki / IRC / JSON).


 * Stop provider stops the current provider so that huggle will stop retrieving new edits. This is useful if you want to keep huggle running but you want to "pause" it.


 * Exit closes Huggle.

Tools menu
This is the Tools menu:



Page menu
The Page menu allows you to view and manipulate the current page.




 * Switch to talk page allows you to switch to the talk page of the current article.
 * View latest revision (Ctrl+V) switches to the most current revision of the page, so you can view it in its entirety.
 * Retrieve History loads more of the history of the page.
 * Show History displays the history of the selected page.
 * Edit (E) allows you to edit a page using a built-in editor.
 * Tag (G) allows you to tag a page with any number of templates.
 * Request deletion allows you to request speedy deletion, propose deletion, or tag an article for a deletion discussion.
 * Request protection brings the page to requests for page protection, where the page can be protected from editing.
 * Watch (L) adds the page to your watchlist, where you can view all changes made to the page.
 * Purge updates the copy of the article on Wikipedia's servers, forcing them to display the most recent version.
 * Mark patrolled (Ctrl+P) marks a new page as patrolled, that is; an experienced editor has looked at it and give the OK.
 * Move allows you to give the article a new title.
 * Restore this revision of the article rolls back all revisions of the page after the current revision, and sets the current revision as the live one.

Queue menu
This is the Queue menu, which relates to the Queue found on the left side of the screen.




 * Next (Space) goes to the next edit in the queue.
 * Trim allows you to trim the queue by time.
 * Clear Current (Ctrl + Space) clears the current queue.
 * Clear all clears all of the queues.
 * Manage Queues allows you to control which queues are available.

HAN menu
This is the HAN menu:



User menu
The User menu allows you to view and manipulate the current page. All of the commands affect the user listed on the bottom of the editor and article history.




 *  Increase badness score
 *  Decrease badness score of user
 *  Talk page
 *  User page
 *  Clear talk page of user
 *  Show user contributions in a browser
 *  Welcome user
 *  Block (Command-B)
 *  Report username
 *  Report user
 *  Manual template
 *  Edit user talk


 * Show user info (?) displays a window with information about the user, including blocks and warnings.
 * Ignore (I) Removes all of the user's changes from the queue>Special:MyLanguage/Manual:Huggle/Queue|queue
 * Retrieve Contributions (U) loads more of the user's contributions
 * View talk page (A) displays the user's talk page.
 * Message (N) allows you to leave a message for the user on their talk page.
 * E-mail... allows you to send an email to the user, if you have set your email in your pref>Special:Preferences|preferences
 * Warn... allows you to warn a user for vandalism. The sub-menu shows all of the options.
 * Report allows you to report the user to the administrators against vandalism page (if you select "Vandalism after final warning") or the usernames for administrator attention page (if you select "Inappropriate Username").
 * Block (CTRL + B) displays a window where you can block the user. This option is only enabled if you are an administrator.

Go to menu
The Go To menu acts as a shortcut to critical areas of Wikipedia.




 * My talk page allows you to go to your talk page on the current project.
 * My contributions allows you to go to your contributions on the current project.
 * Administrator intervention against vandalism allows you to go to the administrator intervention against vandalism page.
 * Huggle sandbox allows you go to a testing page to test Huggle.

Help menu
The help menu links you to all of the information about Huggle.




 * Contents (F1) opens up the default browser and points it to this Manual.
 * Feedback opens up the default browser and points it to Feedback, where you can give the developers bug reports and feature requests.
 * About Huggle... opens up a view with all of the contributors to Huggle. It will look like:


 * [[File:Huggle 3 About Huggle Window.JPG|

Huggle 3 About Huggle window|412x412px]]

Navigation toolbar



 * Browse back and Browse forward will go back and forward through your browsing history, rather than the history of the current page.


 * Open in browser opens whatever is being viewed in your web browser.


 * New tab opens a new tab.


 * Close tab closes the currently selected tab.


 * Previous, next, last, current revision buttons navigate through the history of the currently selected page.


 * Diff to current shows the difference between the older of the two revisions currently selected and the newest revision to the page. Its function is equivalent to the "cur" links on history pages. This can be used to check that the right revision is being reverted to when dealing with situations where multiple instances of vandalism have been partially reverted.


 * Previous, next, last, current edit buttons navigate through the contributions of the currently selected user.

Main toolbar



 * Page
 * View will view the current page.
 * Edit will open a new window containing an edit form for the current page.
 * Tag allows tagging of a page for speedy or proposed deletion, or the prepending of some other tag or tags to the page. Also supports XfD nominations
 * Delete, only available to administrators, deletes the page.
 * Watch will add the page to your Wikipedia watchlist. If the page is already on your watchlist, this button will be highlighted orange, and clicking it will remove the page from your watchlist.


 * User
 * Info will display information about the selected user, including block log, warning log and number of edits.
 * Talk will display the current user's talk page.
 * Message will prompt for a message and post it to the current user's talk page.
 * Report will prompt for an explanation and then issue a vandalism report for the current user. Note that Huggle will do this automatically when appropriate. You may also issue username reports by changing "Report to:". If you are an administrator, this button becomes Block, which will prompt for block summary, time and options and then block the current user.