Version 28 (modified by magnate, 11 years ago) (diff)

Final tidying after the Great Keyword Spamming

Using keywords in tickets

Angband is a big program. There are many thousand lines of code, and dozens of different things to consider when working on it. With a few exceptions (like the maintainer), most developers are interested in specific aspects of the code (user interface, item generation, vaults, savefile handling, whatever). Using keywords in your tickets helps them find the tickets they're interested in more easily, and makes it more likely that your ticket will receive attention.

It's not quite as easy as it sounds. Obviously the worst thing you can do is use no keywords at all, but using too many keywords, and using the wrong ones, are both almost as bad. So the standard keywords you should use are listed below, along with the issues they cover. If your ticket touches on any of these issues, please use the relevant keywords. (The list is not perfect, so please check this page periodically in case it's been improved.)

Keywords should always be used in lower case, and each keyword should be separated by a single space. Please do not use multiple keywords unless they're all relevant - if you can separate the issues, consider opening multiple tickets instead (there is no pressure to minimise the number of tickets). Exceptions to this rule are patch, backport and meta, which should be used as second keywords.

If you want to search for tickets with specific keywords, go to View Tickets and then click Custom Query, and add a filter by keyword.

Platform- and port-specific keywords

  • windows -- if your issue only happens in Windows, please use this keyword. (If you don't know whether it only happens in windows, that's fair enough - someone will add the keyword later when this has been established.) Please do NOT use any other keywords for Windows-related issues (e.g. vista, win7, xp-64 etc.) - if you believe that your issue is related to some specific version of Windows, please state this in the ticket description.
  • unix -- as above, but for Unix-specific issues (e.g. setgid, FHS, X problems etc.). As with Windows, please do not use specific Unices or Linux distributions as keywords, with one exception: please use the keyword "debian" for issues specific to building the .deb, or converting it to some other package format (e.g. RPM).
  • mac -- as above for Mac-specific issues. Again, don't use specific OSs as keywords.
  • riscos -- likewise.
  • sdl -- for the SDL port
  • gtk -- for the Gtk port
  • x11 -- for issues specific to the x11 port (use "unix" for general problems running under X)
  • gcu -- for the ncurses port
  • dos -- for the DOS/IBM port
  • nds -- for the Nintendo DS port
  • port -- for not-yet-created ports (s60, net, gba, qt)

Please do not use any of the above keywords unless you are fairly sure that your issue is specific to that platform or port.

Coding style and compatibility keywords

  • cleanup -- for tickets about cleaning or improving sections of code without changing their effect
  • compat -- for issues such as compiler warnings, C89 compatibility, autotools issues etc. (i.e. a subset of "cleanup")
  • utils -- for tickets about testing and utility code
  • doc -- for issues about documenting the code (c.f. "help" below)
  • backport -- for tickets about importing code from variants
  • patch -- if your ticket has a patch attached
  • gpl -- for licensing issues

Gameplay keywords

  • birth -- for issues related to starting the game (not starting the program)
  • items -- for issues about item generation and monster drops (Too Much Junk, Not Enough Stat Potions, Rubbish Randarts, Boring Curses etc.)
  • id -- for anything to do with identifying or learning items
  • magic -- for effect-related issues including spells, activations and spell-like item effects
  • detection -- for non-magic issues about detection, mapping, disturbance, offscreen death etc. (need a better word because detection makes people think of magic)
  • stores -- for anything related to the stores, including the home
  • ai -- for monster behaviour (but use "magic" for monster spell effects)
  • combat -- for melee and missile combat mechanics, plus LOS/range/projection issues
  • monster -- for monster issues other than recall, combat, drops, ai or magic
  • dungeon -- for level generation, level feelings, traps, vaults etc.
  • player -- for issues relating to the mechanics of stats, resists, classes, skills, food, stealth, speed, timed effects, hp/mp etc.

Metagame keywords

  • help -- for issues related to game documentation, tutorial etc.
  • wizmode -- for anything that happens in wizard mode
  • recall -- for issues about monster and object recall or descriptions (including spell descriptions)
  • squelch -- if your ticket is about squelching or unsquelching
  • prefs -- for loading, changing and saving preferences (c.f. "loadsave")
  • loadsave -- for game loading and saving issues (not pref files, macros, inscriptions or squelch settings but including re-entry)
  • dump -- for anything relating to chardumps, including player history, scores file and the 'C' screen
  • borg -- for issues specific to the borg code

User interface keywords

  • ui -- for general user interface issues (deprecated in favour of anything more specific)
  • display -- for non-graphics display issues such as panel-flipping, status bar etc.
  • graphics -- for general graphics/tile issues which are not port-specific
  • mouse -- as above
  • sound -- as above
  • subwindows -- for issues about the content, function and updating of subwindows (which are not port-specific)
  • commands -- for issues related to game commands, including (auto)pickup
  • keyset -- for roguelike keyset support etc.
  • macros
  • inscriptions

Other keywords

  • meta -- special keyword meaning that this ticket is a consolidation or list of other tickets, not an issue in its own right

Example: if you have an issue about magic devices, think about whether it's about their properties ("items"), their cost ("stores"), their effects ("magic") or your success/failure with them ("player").