HOWTO-Admin

How to add new team members

TODO: Explain what to do *before* adding a new user; and what to do once the new user was added.

Adding new members involves the following things (list may not be complete):

Point out some important rules: follow the Code Formatting Conventions, don't break other people's builds with your commits, etc.
Ensure they are subscribed to scummvm-devel mailing list and suggest subscribing to scummvm-cvs-logs list (commit notifications) as well
Add them to SF.net as project members
- Make sure to also setup appropriate tracker access levels
- Point them to the tracker admin HOWTO below
Add them to Github as project members.
Forum: if they have a forum account, make sure it is in group "ScummVM Team"
Wiki: Make sure they have an account
Ask them to write an Introduction email to scummvm-devel mailing list

How to edit/update webpages

Checkout the scummvm-web respository from github.
Edit the relevant files, e.g. for the downloads page edit data/downloads.xml
Commit your changes as usual

To get any changes you made active on the webserver, you first have to login to the SF.net shell server:

ssh -t USER,PROJECT@shell.sourceforge.net create

Then:

cd /home/project-web/scummvm/htdocs/
./update.sh

More detailed instructions can be found in the relevant sf.net page (which also has information for PuTTY under Windows)

Two important remarks:

Some content on the webpages needs special treatment, e.g. modifying the credits or adding screenshots. If in doubt, ask on scummvm-devel.
Not every project member has SSH access to the shell server. Project admins need to explicitly activate the "Allow access to shell server group space" for individual members. Since there is no good way to track who made which changes on the shell server, it seems like a good idea to keep the number of people with direct SSH access small (but not too small).

How to be a forum moderator

Forum moderators exist to deal with the everyday administration tasks on the forums found here.
This is mainly concerned with enforcing the forum rules.
They should also aim to answer user support requests, point users at various FAQs, wiki pages and otherwise deal with questions posted on the forums (though any developer or other forum user may do this as well).

Spam on the forum is a major issue and any user account which spams junk or commercial messages should have those posts moved to deleted topics or deleted.
If the account is obviously a "spammer" account i.e. only messages are spam, e-mail used is listed as a known spammer account, then the account should be deleted and the e-mail address, IP address and/or user name banned to prevent re-registraion. However, some care should be taken to ban in the way least likely to cause issues for other users i.e. banning a single IP is better than a range etc.
The IP address used to post can be retrieved by an admin from the post by clicking the IP button on the right hand side of the post. The cross next to that is the post deletion option.

Due to the volume of automated spambots registering accounts and then spamming, we have various questions and CAPTCHA to try to exclude mass bot registrations.
As this proved only partially effective, we have now enabled verification of new user accounts by moderators/admins.
When a user registers, an e-mail is sent to all moderators/admins asking them to verify the account. Only after the moderator/admin logs in and then clicks the required link is the account enabled.
When checking a user registration, the admin should first check if the e-mail address and/or username are listed as known spammer accounts here.
If not, then a quick Google for the e-mail address and/or username can confirm whether this belongs to a human user with known gaming interest / normal account activity.
This should quickly exclude most obvious spammers/spambot registrations and include game interested users with a web presence. However, if the result is still inconclusive, then a judgement call should be made.
This will depend on whether the e-mail address is "throwaway" i.e. webmail or other disposable account. We should really reject registrations from disposable accounts such as mailinator.com as they are likely to be problematic in future.
Generally though, if unsure, it is best to give the benefit of the doubt and allow the registration, rather than rejecting legitimate users.

If a user breaks one of the forum rules, some judgement on how to deal with it will be required. However, the following is recommended:

New users may not be aware of the forum rules, so link them to the rules indicating the one that they are violating.
If a user persists in breaking a rule, then it is possible to "give them a warning" by setting this in their user account settings.
If the user still persists or has accumulated three warnings, then disabling their account i.e. banning them is probably warranted.
Locking threads:
- Any thread which is violating a forum rule in of itself i.e. asking for non-freeware game download sites etc. should have a message linking the rule and then be locked to prevent further posts.
- Locking threads should be used sparingly, but is sometimes required i.e. if a discussion has decended to a flamewar or similar.
- In all cases, a message should be posted prior to locking explaining why this has occurred.

How to triage bug reports

Triage is a term borrowed from medical terminology referring to the process of assessing bug reports, prioritising and dealing with any immediate action needed.
We do not have a formal project format and process for doing this, but the following are highly recommended guidelines for dealing with bugs and users reporting bugs:

Some users prefer to ask informally in the Help and Support Forum or in the IRC channel about a bug or problem they are having. As an admin or developer, please don't rebuke them for doing this. However, if their problem appears real and is not solved trivially/immediately, then politely suggest that they file a formal bug and link them to the Bug Tracker.
The current Trackers do send e-mail notifications on new bugs to the scummvm-tracker mailing list, which all developers should be subscribed to. However, this should not be completely relied upon for notification, especially if the "digest" option is chosen and admins should check the tracker periodically, preferably daily for any new bugs.
New bugs should have at least a basic reply comment (preferably within a week), even if this is just thanking the bug submitter for the bug submission and indicating that it will take a little time to deal with.
Any new bug should be assessed for the following:
- Is the bug title line formatted correctly and sufficiently descriptive?
  - Currently, we use the same kind of prefix at the start of the title as we do in commit messages. See Commit_Guidelines#Rules here for description of these. The prefix should indicate the sub-team who should do further investigation i.e. the engine name for engine specific bugs, the backend name for platform specific bugs etc. If unsure, then initially the bug should be assigned to the relevant engine team, rather than the platform team.
  - You should try to ensure that the game short name (and platform, if relevant) are included in the title.
  - These rules are to help developers who browse or search the bug list to locate bugs relevant to their engine or platform by visual or text search.
  - If changing the title from the user's original value, please ensure to transfer any information removed to a comment, if not otherwise present.
- If the bug is missing any of the following required information, then a comment should be added to ask the user to provide the missing information:
  - Name of game (preferably with language/variant).
  - Exact version of Operating System/Platform i.e. Windows XP SP1, rather than just Windows.
  - Exact version of ScummVM by release or source code revision id.
  - Brief description of bug.
  - Method for replicating bug.
  - Attached savegame for replication.
- Any indication that the user has violated Rule #0? If so, then a comment should be posted referring them to Copyright_FAQ by URL.
- The admin should perform a search of the bug tracker, especially with respect to open bugs, to assess if the issue has previously been reported.
  - If the issue has been reported before, but has not been fixed, then a comment referring to the URL of the open bug should be attached, any useful information transferred to the original bug and the bug closed as "duplicate".
  - If it has been reported since the last stable release, but has been fixed in the development repository, then a comment referring to the URL of the fixed bug and indicating that the user should use a daily build or wait for the next release should be attached, prior to closure of the bug with conclusion "out-dated".
  - If the issue has been reported before, but the bug was previously fixed, then a comment referring to the URL of the bug should be attached as this may indicate a regression in the fix, or at least help indicate the cause.
  - Bugs pending information or confirmation of a fix by the user should be set "pending". Originally, the tracker automatically closed these after 14 days or so, unless a comment was added, but this function has been broken/disabled for some time, but they are often closed manually by an admin when it becomes clear they are either lacking sufficient information to be progressed, or fixed/invalid and the user is unresponsive. This is partly why it is important to respond quickly to bugs with insufficient information to ensure that valid bugs are not closed spuriously as the user has got lost in the period of time between submission of the bug and when a developer gets time to look at it.
- If the bug is reporting "a crash", then the first possibility is to eliminate corrupted, missing or variant datafiles. The usual response to this is:

This sounds like corrupted, missing or variant datafiles. Please can you try copying your datafiles  
from the original CD/floppies again and see if the problem disappears?

If this doesn't work, or the user appears to be technically more capable, then a better response is:

This sounds like corrupted, missing or variant datafiles. Please could you attach a text file to this bug  
containing a file listing of your <GAME NAME> datafiles, preferably with file md5sums? The output of a tool such 
as this: http://md5summer.org or other tool from Reporting_unknown_MD5_checksums would be 
optimal.

A developer with the same game should then generate the same type of file listing with md5sums and compare the file attached by the user to see if it indicates that this is the problem.

- If the bug report comments "this used to work" or other indications of a regression, then a comment should be posted asking the user to perform a "gross" bisection:

Can you please test this with previous versions of ScummVM i.e. <list reasonable range/versions of ScummVM 
releases to test, starting with previous version (N-1)> and confirm when this problem was introduced? This will 
greatly reduce the amount of work involved in locating the cause of this bug.

Once the user has confirmed a "bad" and "good" revision, a developer should then try to locate the exact regressive commit using Git bisection and post a followup comment with the id of the regressive commit and the short commit message.

- If a developer some further investigation on a bug, then any lessons, partial conclusions, short useful text debug traces, savegames etc. should be added to the bug tracker item as attachments or comments. This is partly as a medium for discussion of possible solutions, but mainly on more complex or troublesome bugs to checkpoint any progress.