Difference between revisions of "HOWTO-Admin"

From ScummVM :: Wiki
Jump to navigation Jump to search
(→‎How to edit/update webpages: Update the htdocs path)
(→‎How to triage bug reports: First draft of Bug Triage guidelines)
Line 33: Line 33:


== How to triage bug reports ==
== How to triage bug reports ==
TODO: Describe how to react to new bug reports; how to get more info, how to use canned responses; which bug title format we use; etc.
 
[https://en.wikipedia.org/wiki/Triage_%28disambiguation%29 Triage] is a term borrowed from medical terminology referring to the process of assessing bug reports, prioritising and dealing with any immediate action needed.<br>
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 [http://forums.scummvm.org/viewforum.php?f=2 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 [[Trackers |Bug Tracker]].
* The current [[Trackers]] do not have the ability to send notifications by e-mail or IRC based on keywords, so an admin 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.
*** 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 confirm this:
*** 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.
** 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.

Revision as of 07:30, 26 November 2012

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

  1. Checkout the web module from SVN; the current website files are inside "trunk" as usual.
  2. Edit the relevant files, e.g. for the downloads page edit data/downloads.xml
  3. 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>

Two important remarks:

  1. Some content on the webpages needs special treatment, e.g. modifying the credits or adding screenshots. If in doubt, ask on scummvm-devel.
  2. 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 not have the ability to send notifications by e-mail or IRC based on keywords, so an admin 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.
      • 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 confirm this:
      • 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.
    • 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.