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, ...
Ensure they are subscribed to scummvm-devel
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
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
...

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: <syntax type="bash">ssh -t USER,PROJECT@shell.sourceforge.net create</syntax> Then: <syntax type="bash"> cd /home/project-web/scummvm/htdocs/ ./update.sh</syntax>

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

TODO: Explain how to ban a user properly; how to deal with spam; ...

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.