Release New Fun: Difference between revisions

From GCD
Jump to navigation Jump to search
(Postpone TBDs to design phase.)
m (→‎Branding: TM fix)
 
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== GCD Web Site Release: ''New Fun'' ==
== GCD Web Site Release: ''New Fun'' ==


This is the main page for the first release of the new GCD Web Site, code-named ''New Fun''.  This page will holds general release-specific information plus links to documents on specific aspects of the release.
This is the requirements page for the first release of the new GCD Web Site, code-named ''New Fun''.  This page will hold the release requirements information plus links to documents on other aspects of the release:
* [[New Fun Design]]


[back to the [[Web Site Project Page]]]
[back to the [[Web Site Project Page]]]
Line 334: Line 335:
** Any sequence may have a cover image
** Any sequence may have a cover image
** Currently, multiple covers are still stuck together as one image on sequence zero, and will continued to be displayed that way
** Currently, multiple covers are still stuck together as one image on sequence zero, and will continued to be displayed that way
* Feature and title headline each sequence
* Feature and title headline each sequence, with both of roughly equal prominence but distinct from each other
** The word "Feature" is not present
** The word "Feature" is not present
** The feature comes before the title
*** [OPT] Provide a preference to switch this if people complain a lot, as this was split pretty evenly last time it came up
** Sequence number, type and page count are incorporated into the sequence header
** Sequence number, type and page count are incorporated into the sequence header
* Three sections are under the header:
* Three sections are under the header:
Line 439: Line 438:
** TBD during design phase: upper right-hand when localized to RTL languages?
** TBD during design phase: upper right-hand when localized to RTL languages?
** TBD during design phase: Tagline for the GCD?  We currently use several taglines, but sticking with one is more effective for branding.
** TBD during design phase: Tagline for the GCD?  We currently use several taglines, but sticking with one is more effective for branding.
* [REQ] Site is always referred to as either "The Grand Comic-Book Database" or "The GCD"
* [REQ] Site is always referred to as either "The Grand Comics Database™" or "The GCD"
** TBD during design phase: Just plan GCD OK on logos?
** TBD during design phase: Just plan GCD OK on logos?


Line 531: Line 530:
* [OPT] A "reason for change" field will be supplied for a note with submission.  This will help folks figure out what to look for when grabbing it from the pending queue.
* [OPT] A "reason for change" field will be supplied for a note with submission.  This will help folks figure out what to look for when grabbing it from the pending queue.
** [OPT] Pre-populate this with "new index" for new indexes.
** [OPT] Pre-populate this with "new index" for new indexes.
* Fields that must be submitted one at a time to handle complex cases (such as credits and characters) will have an alternate form allowing submission of multiple simple values (exact number of submissions in one form is TBD at design time- perhaps 10?).  Simple values may be edited later to add the complex flags.  Exactly what features are classified as "simple" vs "complex" will be determined during design.


===== Publisher Input Fields =====
===== Publisher Input Fields =====
Line 579: Line 579:
* Name (series title)*
* Name (series title)*


TBD: What to do about publication dates (and implicitly, year began/ended)When all issues are noted, this can be inferred, but if not all of the issue records are there, this is useful to specify separately.
Publication dates can be optionally specified if the set of issues known is incompleteOtherwise it will be inferred from the dates of the first and last issues.


The following fields must link to other database objects, either by validation upon submission or by using some sort of select box:
The following fields must link to other database objects, either by validation upon submission or by using some sort of select box:
Line 587: Line 587:
* Publisher
* Publisher
* Imprint (for the "real" use of imprint, i.e. Vertigo, not for indicia publishers)
* Imprint (for the "real" use of imprint, i.e. Vertigo, not for indicia publishers)
** TBD: Handling publisher/imprint fields while that concept is still a mess.
** TBD at design time: Handling publisher/imprint fields while that concept is still a mess.
* Tracking
* Tracking
** Separate entry for tracking from vs to
** Separate entry for tracking from vs to
Line 593: Line 593:
** May link to an issue in the target series (i.e. the theory that Young Allies continues as All-Winners #21)
** May link to an issue in the target series (i.e. the theory that Young Allies continues as All-Winners #21)
** May link from an issue in this series (i.e. linking from All-Winners #19 to whatever picked up with #20)
** May link from an issue in this series (i.e. linking from All-Winners #19 to whatever picked up with #20)
** This is also useful in weird co-numbering situations, as happened with two Fox series (on of which refers to the co-numbered series by name in the indicia)
** This is also useful in weird co-numbering situations, as happened with two Fox series (one of which refers to the co-numbered series by name in the indicia)


The Format database field will be represented with the following UI elements.  Format values set through this form will be recognized by the UI (see the Display section for details):
The Format database field will be represented with the following UI elements.  Format values set through this form will be recognized by the UI (see the Display section for details).  Exact field values here are starting points, the final lists will most likely be determined by the Sr. Editors:
* Height (inches for U.S. books (?and older UK books, and others?), cm otherwise)
* Height (inches for U.S. books (?and older UK books, and others?), cm otherwise)
* Width (inches for U.S. books (?and older UK books, and others?), cm otheriwse)
* Width (inches for U.S. books (?and older UK books, and others?), cm otheriwse)
Line 625: Line 625:
The following flags do not correspond to any current fields, and will be handled through the migration column:
The following flags do not correspond to any current fields, and will be handled through the migration column:
* Volume Number Display (with the following options):
* Volume Number Display (with the following options):
** Note that this flag will be ignored if numbers like v1#2 are present (TBD: ignore always for this release?). It is intended to aid future migration.
** Note that this flag will be ignored if numbers like v1#2 are present (TBD during design: ignore always for this release?). It is intended to aid future migration.
** The field will have the following options
** The field will have the following options
*** Show volume (if present) separate from issue number (this is the default)
*** Show volume (if present) separate from issue number (this is the default)
*** Show volume as part of issue number (TBD: what if this only applies to some issues?)
*** Show volume as part of issue number (TBD during design: what if this only applies to some issues?)
*** Show volume in place of issue number
*** Show volume in place of issue number


Line 892: Line 892:
* Cross Site Request Forgery protection
* Cross Site Request Forgery protection


== Feature Specifications ==
[[Category: GCD Technical]]
 
Detailed feature specifications will be recorded in Bugzilla under the ''New Fun'' milestone so that they may be assigned to developers and tracked.
 
== Test Plans ==
 
=== Test Data ===
 
=== View-Level Tests ===
 
=== Layout and Navigation Tests ===
 
=== Performance ===

Latest revision as of 18:00, 12 September 2022

GCD Web Site Release: New Fun

This is the requirements page for the first release of the new GCD Web Site, code-named New Fun. This page will hold the release requirements information plus links to documents on other aspects of the release:

[back to the Web Site Project Page]

Release Goals

  • To implement the minimum set of functionality required to deploy to production:
    • Display capabilities no more limited than what we have now.
    • Modification capabilities similar to what we have now, but with as much as possible subject to an approval workflow.
    • Full edit access restricted by user permissions for anything that is not yet under an approval workflow.
  • To support the existing data and schema, with only the following minimal modifications:
    • Drop unused columns.
    • Migrate user management to Django's authorization framework.
    • Additional tables/columns needed to implement the full workflow.
  • To lay the groundwork for a new look-and-feel (including navigation and search capabilities) of the site which will support our growth into the new schema.
  • To thoroughly support internationalization.
    • UTF-8 support throughout the code and display.
    • Localization for all countries/languages currently involved in the GCD which have native speakers available to provide text.
  • To ship with a test suite that will support rapid but reliable future growth.

Release Timeline

Note that this list implies a rather strict separation between phases (such as feature specification and coding, for instance). It is likely that these will actually overlap in various ways, and this section will be updated to reflect that.

  • Detailed Requirements: 2008-11-02
  • Design Specification and initial round of Bugs in Bugzilla: 2008-12-14
  • Test Plans: TBD
  • Test Data: TBD
  • Code Complete (includes automated tests): TBD
  • Deployment: TBD

Detailed Requirements

Throughout this section, [REQ] denotes a hard requirement, without which the release may not ship. [OPT] denotes an optional requirement, which may be bumped to a later release but is included because it is thought to not add much time over the hard requirements, or because it is particularly desirable. [OPT] requirements will mostly either become [REQ]s or move to a later release as planning solidifies. [NON] designates a non-requirement- a feature that is explicitly deferred to a later release, but is mentioned here for clarity.

Requirements that don't have a tag should be considered [REQ].

Look and Feel

The site should have a consistent look and feel for all areas.

Fonts and Font Sizes

  • Font sizes must be specified in a way such that all supported browsers can resize the fonts through the normal mechanisms
  • Specific fonts and sizes will be chosen during the design phase

Colors

  • Color scheme will be adjustable through default and user-contributed style sheets.
    • Support for user-contributed style sheets is not part of this release, but internal code should allow it.
  • Specific colors and color scheme roles (background / foreground colors, title bar colors, text colors, menu colors, etc.) will be chosen during the design phase.

Navigation

The GCD will use a fairly standard layout for navigation, with the global navigation across the top and loal navigation down the left side (TBD in the design phase: possibly flipping to the right side in RTL locales). The global navigation will include widgets for switching between sections, running basic searches and logging into the site. Local navigation will be specific to a given section or page type, for instance listing the sequences on an issue page. Supplemental navigation will include site maps and guides, and be in a separate area accessible through the Global Navigation.

Global Navigation

  • [REQ] Global navigation will occupy the top of every page
    • [OPT] The front page may have a customized by stylistically consistent version of global navigation
  • [REQ] The basic search box will be part of global navigation
  • [REQ] The login form w/ registration link will be part of global navigation
    • [REQ] When logged in, this should be replaced by the user's name and a link to the preferences, if preferences have been implemented.
  • [REQ] The following options will be present (as menu items, tabs, etc.- TBD during design) Sections marked as [OPT] are so marked because the area to which they link is optional for this release.
    • [REQ] Home
    • [OPT] Browse
    • [OPT] Advanced Search
    • [REQ] Preferences
    • [REQ] Contribute (alternate name? This means contribute info, not money)
    • [OPT] Help
    • [REQ] About

Global Footer

  • [REQ] Includes all necessary legal disclaimers
  • [REQ] Includes error reporting links
  • [REQ] Donate button
  • [REQ] Top of page link

Local Navigation

As is implied by the name, Local Navigation will take different forms depending on what section we are in and what is being displayed in the main content region.

  • Local navigation will be implemented as a sidebar to the left of the main content region
    • TBD during design phase: Switch to the right when displaying in an RTL locale?
Defaults
  • [REQ] If browsing is implemented, then the default local navigation for areas that do not have content requiring local navigation should be the browse navigation.
  • [REQ] The following areas may not have need for local navigation, since they either have little content, or will link to documents on the wiki rather than documents stored within the web site application, or just don't have enough subsections on the page to need a menu:
    • Home Page
    • Contribute
    • Preferences
    • About
    • Publisher view
    • Series view
    • Cover galleries
  • Links to add new publisher, series or issue records should be present in the local navigation of the following areas:
    • Browsing
    • Searching
    • Data display
Browse

Browsing is an OPT feature of this release. A [REQ] here means "required if Browsing is implemented at all".

  • [REQ] Switch between areas of browsing (publishers, series, etc.)
Advanced Search
  • [OPT] If advanced search is implemented, local navigation may allow switching between specialized search forms
Help
  • [OPT] Links to various help topics for using the site. Most often, folks will end up on one of those pages directly by clicking a help link. Assuming help gets implemented in this release beyond the very basics.
Issue View
  • [REQ] Sequence-by-sequence links, as currently implemented in the right-hand box. Moving this will make layout more consistent. Not to mention much easier to implement.

Supplemental Navigation

  • [OPT] Implement a guide / tutorial to functionality as part of the help section
  • [OPT] Site index? Not sure how this works, especially since much of our non-DB information is on the wiki, not the site. Maybe an index could show where everything lives, whether on the site proper or not. Note that the wiki and other things will be hosted on comics.org at this point.

Search

The focus for search in New Fun will be the search box- the primary interface seen on the front page and as part of the global navigation of the site. This is because it is the search interface that is immediately available to the user, and the one the vast majority of users will use. Advanced search generally appeals to a much smaller set of users, especially if the search box is well designed. It will be present only in a basic form, or possibly even deferred to More Fun. It is important to take advantage of this major change in the UI to get the user base accustomed to a new way of using the search box. Changing its behavior drastically *after* the main UI change is likely to be much more confusing.

The Search Box

The ideal interface for the main search form on a web site is a single text box that by default searches the entire site, considering each term separately unless they are grouped by quotes. However, this works best when each sort of thing the user might want to search is represented by its own database object. This is true of some things in our site (publishers, series, issues, sequences), but not yet true of others (creators, characters, features).

Because of this and some other cases where specific searches are needed (i.e. reprints), we will continue with a zoned search system instead of a single box. However, we will move incrementally toward the single box model by reducing the number of zones in the menu and in exchange allowing more specific requests to be made through search terms. This follows the model broadly popularized by Google, whose search box behaves very simply, but allows a number of advanced features if one pokes around enough. Our search results will include hints to people as to how to better format their search, in addition to the traditional help page.

  • [REQ] Of the form "Search [menu] for [textbox] (Go)"
    • TBD during design phase: If results tables cannot be re-sorted, we probably still need the "by name" vs "by year" sort selection as well
  • [REQ] Search zones (the stuff in [menu]):
    • Comics
      • This covers both series and issues. By default, it returns series.
      • [OPT] Trailing numbers (including comma-separated lists and ranges) will be parsed as issue numbers, causing a sets of issues to be returned instead of series.
        • Numbers at the end of a series title can be quoted to avoid this behavior.
        • See mycomicshop.com (among others) for an example.
        • A starting issue before the first issue or an ending issue after the last issue will be treated as the first and last issue, respectively.
        • [NON] Non-numeric issues cannot be found by this method. Advanced search or the search box functionality of a future release will address this.
    • Publishers
      • As with the current OI, this should return both top-level publishers and imprints, and just make it clear in the results which is which.
    • Credits
      • Searches Script, Pencils, Inks, Colors, Letters, Editing and returns sequences.
      • Each field is also present as a separate, specific search zone.
      • [OPT] Instead of individual search zones, have one zone for Credits (or even one zone for sequence-based searches) and specify fine-grained restrictions in the search text, like Google does with its qualifiers (i.e., on Google site:comics.org will restrict the search for all other terms to pages on comics.org)
        • This could allow more fields to be searched without bloating the UI.
    • Stories (Sequences?)
      • Searches sequence title and feature. Returns sequences.
      • [OPT] Split this and provide separate search zones for titles and feature.
    • Characters
      • Searches feature and character appearances. Returns sequences.
      • Feature is searched only because so many sequences fail to list the feature character in the character appearances, or fail to list characters at all.
    • Reprints
      • Searches reprint notes. Returns sequences.
  • [OPT] Implement keyword searches, and use as the default in place of phrase searches.
    • By default, look for any keyword, not all.
    • Implement stop words ("the", "a", "an", "and", etc., need international list)
    • Allow grouping into phrases (words and phrases are known as "terms")
    • Allow required terms
    • Allow excluded terms
    • Allow searching for things that start with a term (with other terms searched anywhere in the text)
    • Allow searching for an exact match with a single term

Results Display

  • Results will be displayed in paginated tables (see Pagination under the general Display section)
  • TBD during design phase: Implement re-sortable tables? How to handle re-running query vs expectation of fast re-sort?
Publisher / Imprint Results
  • Country (with name, not just flags)
  • Name (Link to publisher / imprint page)
  • Classification (publisher vs imprint, possibly more information if newer flags are present, i.e. for assigned names or indicia publishers)
  • "Parent" or "Imprints" link
  • Years active
  • [OPT] number of series
Series Results
  • Country and Language (with names, not just flags)
  • Series Title (Link to series display page)
  • Year range
  • Number of issues (no link, because index grid is on series page)
  • Number of covers (link to cover gallery- cover status is on series page)
  • Publisher (link to publisher)
  • Imprint (link to imprint)
Issue Results

If we implement the search feature of allowing issue ranges to be appended to series name searches, we will get sets of issues instead of individual series.

  • Country and Language (with names, not just flags)
  • Series Title (link to series display)
  • Issue number (link to issue display)
  • Cover date
  • Publisher (link to publisher)
  • Imprint (link to imprint)
Sequence Results

Same fields as issue results, plus:

  • Sequence title (links to sequence within the issue)
  • Sequence feature
  • Matched values
    • Credits for credit searches
    • Characters for character searches
    • Reprint notes for reprint searches
      • Sequence results for a reprint search shows sequences with the searched values in their reprint notes field
    • TBD during design phase: Other matches depending on how much gets implemented with search.
      • Matches should all be in one column, one matched field per line if there are multiple matches.
  • TBD during design: Field set may be adjusted to avoid horizontal scrolling.

Narrowing Results

  • [REQ] Code structure must support adding functionality of this sort.
  • [OPT] Narrow with another search (same search box functionality), ANDed to existing search. Will require more details if this is to go into this release.
  • [OPT] Broaden search by ORing new terms to the existing search. Will likewise require more details if pursued.

Advanced Search

  • [OPT] Support searching every field to some degree.
  • [NON] Complex searches along the lines of Bugzilla's Boolean charts should be deferred to a later release.

Browsing

Browsing is an [OPT] feature for this release

  • Initially only publishers/imprints and series can be browsed. As we migrate to the new schema, more browsable objects will exist
  • Users must choose a letter of the alphabet to browse (or choose a numbers/symbols category)
    • Non-Latin-1 charsets will be handled later, once we have enough such data to worry. For now they can go in one category.
  • Matching records will be displayed in tables of the same format as search results, and paginated the same way

Migration Tools and Fields

  • [REQ] SQL script to drop unused colums and migrate user data in to Django tables.
  • [REQ] Python script to migrate passwords from plain text to encrypted.
  • [REQ] Reprint parsing will be off by default *unless* it can be enabled in such a way that Action Comics #1 loads within the performance requirements.
    • Users logged in with Editor or Administrator privileges will be able to turn on reprint parsing on a page-by-page basis.
    • [OPT] Users with Editor or Administrator privileges may be able to turn on the faster version of reprint parsing globally through a preference, which will be set to off by default.
    • [OPT] Python script to flag reprint notes that the parser can recognize in a migration field (see below). This can be delivered as a standalone tool outside of the release, though.
  • [REQ] Each of the publisher, series, issue and sequence tables will be given an additional column in which to store migration data. See the section on Editing for the details of how this will be used. General use cases include:
    • Flagging whether a record has been examined for some migration issue yet, and if so whether it has been corrected or if it needs some additional information that is not yet known.
    • Storing information that the new UI can capture and that has space in the new schema, but that does not yet have space in the current schema.
  • [REQ] Editors must be able to search based on this information to track migration status and find records that require attention.

Display

  • All record display pages will have the following structure:
    • Main heading bar
    • Secondary heading bar
    • Data area
  • Any text referring to another record links to that record
  • Paginated data will display links for next, previous, first, last and nearby pages
    • Pagination links will appear in the secondary heading bar and in a similarly-styled footer
  • A text box for jumping to an arbitrary page will be present if not all pages are represented by links

Publishers

  • Main heading bar:
    • Publisher name
  • Secondary heading bar:
    • Year began / ended
  • List of imprints (Paginated at 100 records)
    • TBD: Alternately, a link to show imprints, using the search results format
  • Link to series published, using the search results format
    • TBD: Alternately, an inline paginated table

Imprints

  • Same as Publishers, but with parent publisher also in the main heading bar

Series

  • Main heading bar:
    • Series name
    • Year began
  • Secondary heading bar:
    • Publisher name
    • Imprint name
      • TBD: How to handle absurdly long compound imprints- probably say "multiple imprints" if length over 60 characters or something
  • Data region:
    • Medium-size image of first available cover
      • Link to cover gallery near cover image
    • Publication dates
    • Number of issues published
    • Country and Language
    • Format
      • If migrated data is present, display individual fields, and only those relevant to the series
    • Publication Notes
    • Notes
    • Tracking
    • Indexer credits
      • Credit work on the series record
      • Series-level issue indexing credits that can't be migrated to issue-level credits
    • Index status table
      • All issues numbers are links to issues
      • Also have a text box to enter an issue to go to if the table is large so the user doesn't have to hunt for the number (TBD: What is "large"?)
    • Cover status table, if there are missing covers
    • For all lists and tables of issues, the cover sort codes should be used rather than the key dates.

Issues

  • Main heading bar:
    • Left side:
      • Series name
      • Series year began
      • Issue number
    • Right side:
      • Publication date
  • Secondary heading bar:
    • [OPT] Country flag
    • Publisher name
    • Imprint name (same as with series for long names)
  • Issue content region:
    • Price
    • Page Count
    • Format data
      • Split into fields if migrated data is present
    • Editor credits
    • Indexer credits
    • Sequences in order, top to bottom
  • Local navigation area handles next/previous issue links and links to the individual sequences

Sequences

  • Displayed on the issue page
  • Cover image on the left if there is one
    • Upload link if there is no image available
    • Zoom links close to the image
    • Any sequence may have a cover image
    • Currently, multiple covers are still stuck together as one image on sequence zero, and will continued to be displayed that way
  • Feature and title headline each sequence, with both of roughly equal prominence but distinct from each other
    • The word "Feature" is not present
    • Sequence number, type and page count are incorporated into the sequence header
  • Three sections are under the header:
    • Credits
    • Content
      • Genre
      • Reprints
      • Characters
      • Synopsis
    • Notes

Cover Galleries

  • Same heading bars as for the series page
  • Small cover size
    • Links for small, medium and large, goes to same page as similar links from issue page
  • Five covers wide, ten rows per page
  • Covers that are not present or marked for replacement should have upload links
    • TBD during design phase: sparse cover problem. Option to show only uploaded covers? Default is to show placeholder upload links so people realize what is missing.
  • Clicking on the cover (or cover placeholder) goes to the index
  • Upload links will be present near each cover
  • Covers marked as needing replacement must be clearly visible (by color code or some other means)
    • Note that a cover no longer needs to be marked before it can be replaced, but covers may be marked to encourage replacement and to show up in queries.

Cover Zoom

  • Same heading bars as for the issue page
  • Same next/previous links as issue page
    • Move to the next/previous issue cover in the same size
  • Links to allow switching between sizes
  • Clicking the cover goes back to the issue details

Special Cover Displays

  • Recently added covers and covers needing replacement
  • Main header just says the name of the query
  • Secondary header is blank
  • Otherwise same as the galleries

Internationalization

  • [REQ] All text encoded in UTF-8.
  • [REQ] Database migrated to UTF-8 encoding.
  • [REQ] Layouts friendly to LTR and RTL languages / bi-directional display
    • Bi-directional display will be needed if, for instance, the overall page is localized to an RTL language, but the user is viewing a record with data in an LTR language. Or vice versa.
    • [REQ] CSS structured to make switching between LTR and RTL layouts easy.
    • [OPT] Actual functioning RTL layouts need not be implemented in this release. We just should not make them difficult. This statement takes precedence over any other statements about RTL layout that may still be scattered about the requirements section.
  • [REQ] Layouts robust to character / word / phrase size changes.
    • Parts of the existing "new" layout rely on a specific width of text to avoid overflowing an area of the page. These assumptions should be removed.
  • [REQ] All label text should be set up for localization.
  • [OPT] All error messages, help text and front page verbiage should be set up for localization.
  • [REQ] Data should be localized based on the country code of the publisher or series (whichever is most specific and relevant), while labels and other text should be localized based on the browser's locale.

Localization

  • TBD: Need list of locales to be supported in this release, and translators for them.
    • French (Leonardo De Sá)
    • German (Jochen Garcke)
    • Portuguese (Leonardo De Sá)

Accessibility

  • [REQ] Must support screen readers (alt text, labels, etc.)
  • [REQ] Must render decently on an 80-column text browser.
  • See also mobile browser support.

The Front Page and Other Non-Data Displays

  • In addition to the search box and other elements of global navigation and branding described elsewhere, the front page will have:
    • Links to newly uploaded covers and covers needing replacement
      • Legal disclaimer about explicit cover images
    • News items
    • Invitation to contribute (in more detail than just the link saying "Contribute")
  • The Contribute page will:
    • Provide brief explanations of contributing as an indexer or error reporter
    • Provide a brief explanation of the role of editors and the approval process
    • Link to more detailed documentation on the wiki
  • The Preferences page will:
    • Display basic account information
    • Allow edits to name, nationality, email and password fields
    • Display role information (Indexer, Editor, Admin)
  • The About page will:
    • Quote the first paragraph of the charter
    • Give a brief history of the GCD
    • Provide links to more detailed documentation on the wiki page
  • [OPT] The Help page will:
    • Link to pages documenting how various parts of the system are used including
      • The search box
      • Browsing (if implemented)
      • Editing
      • Reporting errors
    • Some of this content may be on the wiki

Branding

  • [REQ] The GCD logo shall be displayed in the upper left-hand corner of every page
    • TBD during design phase: upper right-hand when localized to RTL languages?
    • TBD during design phase: Tagline for the GCD? We currently use several taglines, but sticking with one is more effective for branding.
  • [REQ] Site is always referred to as either "The Grand Comics Database™" or "The GCD"
    • TBD during design phase: Just plan GCD OK on logos?

Advertising

  • [REQ] Space must be available at the bottom of most pages for Google Ads, as seen on the current site.
  • [REQ] Prominent space must be available on the home page for ads for the CBLDF or other comics-related charities or causes as determined by the board.
  • TBD: Google ads at the bottom of the front page?

User Profiles and Preferences

  • [REQ] Architectural support for user profiles and preferences (per user and per session).
  • [OPT] The ability to set preferences.
    • Search result order?
    • Display options? (filter out certain types? filter out synopses?)

Workflow

Unlike in the current system, all records (publishers / imprints, series and issues) must be reserved for editing and go through the approvals process. This applies equally to new skeleton records, unindexed issues, or existing issues to be edited. Implementing this will allow indexers to do more work without sacrificing quality control.

User Roles

Throughout this section, "users" refers to editors, indexers, and unregistered potential indexers as a whole. "Approver" refers to any user who can approve changes (typically editors).

  • Anyone with a registered account has Indexer privileges, and can make any edit as described in the Editing section. They may not approve any changes.
  • Accounts with Editor privileges can do anything Indexers can do, and can approve changes.
  • All changes must be approved by editors, no matter the role of the user making the change, and an editor may not approve his or her own changes.

Reservations

Reserving a record should be easy, but all such reservations should expire within reasonable amounts of time. Indexers or editors who tie up records should be prevented from reserving more until their existing backlog is completed or released. This process should be flexible enough to handle the varying amounts of time indexers have available to contribute.

Individual Reservations

There will not be a separate reservations UI. Records (issues, series, publishers) can be reserved in several ways:

  • [REQ] Users can click the "Edit" button on the record's page.
    • [REQ] Logged-in users get a confirmation dialog with the expiration date of the reservation, so that they understand they are reserving the record, and that it will be locked until they release it or until the reservation expires.
    • [REQ] Anonymous users will be prompted to log in or register before seeing the confirmation box and being allowed to reserve / edit the record.
  • [REQ] Users can select records from a search results table and clicking a "Reserve" button. This will only be visible for logged-in users.
  • [REQ] Reservations initially expire after one month (but see extension functionality below).
  • [REQ] Reserving a parent record does not prevent child records from being added, changed, moved or deleted.
    • [REQ] This applies to publishers->imprints, publishers->series, imprints->series, series->issues.
    • [REQ] Sequences are always reserved along with their issues. This may change in the future, when sequences can be shared among multiple issues, but in this release that is not the case.
Reservation and Record Creation
  • [REQ] Newly created records, including skeletons, will go through the approval process. They may be created in one of several ways:
    • [REQ] "create and submit" places the records directly into the pending queue.
    • [REQ] "create and reserve" places the records into the creator's edit queue to allow further work.
    • [REQ] Issues created at the end of series with on-going reservations are always added to the reserver's queue, and can only be created as skeletions.
On-Going Reservations
  • [REQ] Series pages and results table entries will also allow the creation of an on-going reservation.
    • [REQ] If a series has an on-going reservation, anyone may create issues for the series, but only as basic skeletons
      • [REQ] This means an issue number and sort code, and maybe a publication date (TBD), which will also allow for a cover scan upload.
      • [REQ] Only the reservation holder can add further data.
      • [REQ] Once the new issue is submitted by the reservation holder, it is available for anyone to reserve for further edits.
    • [REQ] Only new issues added to the end of the series run are automatically reserved by the on-going reservation. Existing issues and issues added before the beginning of the reservation period are still open to the normal edit / reserve process.
    • [REQ] On-going reservations expire every six months, but may be renewed during the last month of each period.
    • [REQ] The expected frequency of a title over the next six months must be specified in the reservation (monthly, weekly, or simply an expected number of issues). This has to do with expirations and renewals, as described in the next section.
Expiration, Renewal and Extension of Reservations

Note: All time values here are suggestions to start discussions. Exact times will most likely be determined by the board.

  • Reservations with no changes are immediately released upon expiration.
  • Reservations with changes are not expired, but the user will not be allowed to reserve additional issues until all overdue reservations are submitted or released.
    • After a grace period (one week?), the indexes will be automatically submitted for approval, and marked as submitted due to expiration rather than user action.
  • Reservations may be extended at any time, up to the maximum reservation length of 3 months (from the original reservation date, not from the time of extension).
  • [OPT] Email notification one week before the reservation expires.
  • [OPT] Editors may extend reservations other than their own up to 6 months, to accommodate particularly complex projects like large anthologies.
  • On-going series reservations may be renewed during the final month of each period.
    • If the indexer is more than one month behind, the reservation may not be renewed (i.e. more than one unsubmitted issue for a monthly (or any more rarely published series), more than 2 issues for a twice-monthly, more than 4 issues for a weekly, etc.)
    • [OPT] Email notification at the beginning of the final month of a registration period.
Reservations and Display
  • [REQ] Reserved records (individual or on-going) will show the reservation holder's name and the reservation's expiration date in place of the Edit or Reserve button.
  • [OPT] A form for contacting the reservation holder without disclosing their email address may be provided.

Editing

Once a record has been reserved, it may be edited repeatedly until it is ready for submission for approval, or is abandoned and released for others to edit. In this section "Editor" always means the user role of Editor, not simply a generic user who is editing the record. Generic users are referred to simply as "users".

  • Edit screens will be based on the display screens
  • Edits will not be reflected in the display until after approval
    • [OPT] Editors may view a record as it is being edited, and when logged in they will see a button that allows this.
  • The following functions will be available to the user while editing:
    • Submit for Approval
    • Save Changes (without submitting)
    • Discard all changes and release reservation
    • Extend reservation (up to the maximum duration, as described above)
  • [OPT] A "reason for change" field will be supplied for a note with submission. This will help folks figure out what to look for when grabbing it from the pending queue.
    • [OPT] Pre-populate this with "new index" for new indexes.
  • Fields that must be submitted one at a time to handle complex cases (such as credits and characters) will have an alternate form allowing submission of multiple simple values (exact number of submissions in one form is TBD at design time- perhaps 10?). Simple values may be edited later to add the complex flags. Exactly what features are classified as "simple" vs "complex" will be determined during design.
Publisher Input Fields

The following fields have a simple text box for value input (starred fields are required before submission):

  • Name*
  • Year Began*
  • Year Ended (linked to a checkbox marked "Active", and can only be filled out if "Active" is unchecked)
  • URL (validated for syntax when saved)

The following fields are free-form text:

  • Notes

The following fields must be validated against the database (either by using a select box of some sort, or by validating the contents when the field is saved):

  • Country*
  • Parent publisher
  • [OPT] The following options will be handled in the migration column. They are all off by default:
    • Imprint (available only if a parent publisher is set)
    • Indicia publisher
    • Multiple indicia publishers
      • Either this or Indicia publisher may be set (or neither), but not both
    • Assigned name
      • If this is set, then none of the other option flags may be set

In this UI (as will be made clear by the help text) the imprint flag indicates that this publisher is not only an imprint in our database (which just means that it has a parent publisher), but actually meets our (TBD) definition of an imprint, as opposed to just being a convenient place to shove indicia publishers or other corporate names that don't quite fit. Assigned name exists to flag publishers that don't correspond directly to any real-world corporate entity. The following table illustrates the use of flags (at least somewhat, as this is a contentious area- not all examples currently exist in the database):

Name Has Parent? Assigned Name? Imprint? Indicia Publisher? Multiple Indicia Publishers? Notes
Marvel No Yes No No No As far as I know, "Marvel", just one word, is not used in any indicia.
Timely Yes Yes No No No This is not the legal name of any company, but is the group name given to the earliest phase of what's referred to overall as Marvel.
Timely Comics, Inc. Yes No No Yes No Appeared in excatly this form the indicia of numerous issues.
Timely Publications: 1-20; Complete Photo Story: 21-68; Marjean Magazine: 69-75 Yes No No No Yes Set of indicia publishers used for Captain America Comics. Flagging this separately lets us find these more easily when migrating later.
Vertigo Yes No Yes No No Vertigo is definitely an imprint. As for indicia publisher, casual survey of Vertigo issues and trades shows that they seem to use a DC corporate name for that.
Oni Press, Inc. No No No Yes No This is a real corporate name (so not an assigned name, even if it has child imprints).
Series Input Fields

Starred fields are required to be filled out before submission for approval.

The following fields will have a simple text box for value entry:

  • Name (series title)*

Publication dates can be optionally specified if the set of issues known is incomplete. Otherwise it will be inferred from the dates of the first and last issues.

The following fields must link to other database objects, either by validation upon submission or by using some sort of select box:

  • Country
  • Language
  • Publisher
  • Imprint (for the "real" use of imprint, i.e. Vertigo, not for indicia publishers)
    • TBD at design time: Handling publisher/imprint fields while that concept is still a mess.
  • Tracking
    • Separate entry for tracking from vs to
    • Must link to a series record
    • May link to an issue in the target series (i.e. the theory that Young Allies continues as All-Winners #21)
    • May link from an issue in this series (i.e. linking from All-Winners #19 to whatever picked up with #20)
    • This is also useful in weird co-numbering situations, as happened with two Fox series (one of which refers to the co-numbered series by name in the indicia)

The Format database field will be represented with the following UI elements. Format values set through this form will be recognized by the UI (see the Display section for details). Exact field values here are starting points, the final lists will most likely be determined by the Sr. Editors:

  • Height (inches for U.S. books (?and older UK books, and others?), cm otherwise)
  • Width (inches for U.S. books (?and older UK books, and others?), cm otheriwse)
  • Height and Width will be in measurements as follows:
    • Inches to 1/16" for U.S. books (and UK? before a certain time? Any others?
    • Metric for all others, and by default if there is a question.
    • Named sizes such as Golden Age/Silver Age/A4/Albenformat/etc., TBD by Sr. Editors
  • Interior color
  • Cover color
  • Color fields will accept the following values:
    • Full Color
    • Black and White
    • TBD: other values such as grayscale or duotone?
    • TBD: [OPT] Allow free text to handle unusual situations?
  • Binding (which accepts the following values):
    • Saddle-Stitched / Stapled (through fold- how to describe this?)
    • Stapled (across fold- how to describe this?)
    • [need to dig up the other terms and their definitions- squarebound? perfect?]
  • Cover stock
  • Interior paper stock
    • [Need terms and descriptions]
  • Flags/checkboxes for mini-series, max-series, on-going [what else? hardcover? tpb?]
    • Dust jacket (what else needed for this? on hardcovers, more rarely on nice softcovers)
    • Slipcase (what about when slipcased with other volumes/issues? Should be covered in notes field)

The following field will be represented by a free-form text area:

  • Notes

The following flags do not correspond to any current fields, and will be handled through the migration column:

  • Volume Number Display (with the following options):
    • Note that this flag will be ignored if numbers like v1#2 are present (TBD during design: ignore always for this release?). It is intended to aid future migration.
    • The field will have the following options
      • Show volume (if present) separate from issue number (this is the default)
      • Show volume as part of issue number (TBD during design: what if this only applies to some issues?)
      • Show volume in place of issue number

The following fields that are now visible will not be explicitly visible or editable:

  • First and Last Issue
  • Issues indexed
Issue Input Fields
  • Issue skeletons may be added with just issue number and sort code information
    • Existing single and multiple issue addition options will be preserved
      • Add multiple- contiguous range
      • Add multiple- volume / issue
      • Add multiple - year / issue a.k.a. "Euro"
    • [OPT] If multiple skeletons are added, the whole group is submitted for approval as a unit

An issue and its sequences may be edited all on one page.

TBD: While properly a design rather than requirements issue, meeting the full requirements of editing everything on one page in a usuable manner will probably only be practical with liberal use of AJAX. The strategy for editing when JavaScript support is not present must be determined, unless we decide that while display must work without JavaScript, editing may require it. Options for edit support without JavaScript include:

  • Reloading the whole page whenever any information needs to be written back to the database or the session (for instance, adding a new sequence, or adding a credit or character to a sequence since those will no longer be free-form fields). This could be prohibitively expensive for a large index.
  • Splitting the edit into multiple pages, at least one page per sequence, possibly with sub-pages for things like adding credits or characters. While less appealing in many ways, if the performance of the site is improved, this may be more usable than one mega-page. It may also be easier to code.

The following issue-level fields will use a simple text box for value entry:

  • Issue number
    • A linked checkbox may be checked to indicate that there is no number, which will produce the appropriate text (currently '[nn]') automatically.
    • 'nn' and '[nn]' will not be allowed- the error message will suggest checking the box.
    • [OPT] UI for indicating made-up numbers, or cover vs. indica numbers. This will probably get punted to the More Fun release.
  • Volume number (linked to a checkbox that must be unchecked to indicate that a volume number is present)

Sort code:

  • Plain number, decimals allowed.
  • Drawn from the cover sort code for existing records.
  • Rather than directly entering numbers, user can specify:
    • At end of series
    • At beginning of series
    • After/before/between existing issues
    • Note that if the ordering is unknown, some guess must be made to avoid unpredictable display behavior

Publication Date:

  • Modified date form
  • Extra months (pairwise, seasonal, "Holiday", no month)
  • "Early", "Mid", and "Late" modifiers for bi-monthlies or odd schedules
  • Day (for weeklies)
  • Checkbox for irregular dates- when checked a plain text box may be used to enter an unusual date.
  • Dates entered or confirmed through this UI will be marked as "migrated".

Price:

  • UI to enter one price at a time ("Add Price")
  • Text box for decimal number
  • Drop down for ISO codes
  • Drop down for country codes (optional- used when multiple prices in same currency for different countries)
  • Checkbox and separate text box for irregular prices
  • Options will exist to specify "free" and "no price"
  • [OPT] checkbox to flag newsstand prices

Credits:

  • For adding editors, publishers, other issue-wide credits.
  • Still read from and stored in sequence 0's Editing field, but marked as "migrated" in the migration column.
  • See the sequence credits section for a detailed description of how this field works and enforces formatting rules.

Page Count:

  • Simple text field (with numeric validation)
  • Read from and stored in sequence 0's page count field.
  • Option to mark page count as uncertain (with number) / unknown (no number)
  • TBD: Migrating '?' entries?
Sequence Input Fields

See the Issue Input Fields section for notes about issue and sequence data being edited together on one page. While the input requirements for some of these fields (esp. credits and characters) are elaborate, they will provide a tremendous value in eliminating the confusing and inconsistently enforced punctuation problems, and allow for more readable presentation than the current display formats.

  • Input fields that take multiple values will be designed to add, edit or delete one value at a time to eliminate problems with separator punctuation
    • Existing data will be editable as a block, but help text will encourage re-entering it.
    • Data in any such field that has only been entered through the new system will be marked as migrated.

The following fields will have simple text boxes for value input:

  • Title
    • Flags for "untitled", "made-up title", "title from script"
  • Feature
  • Sequence number
    • On sequence creation, the sequence can be set to appear before an existing sequence, automatically adjusting the numbers of the following sequences
    • Likewise, a sequence can be moved which causes the other sequences to shift accordingly


The following fields will have large text areas for value input:

  • Synopsis
  • Notes

The following fields will use drop-down menus of values drawn from the formatting documentation:

  • Type
  • Genre
    • TBD: Genre may have an extra text box for free-form secondary genres, which should be added one at a time.

Page Count:

  • Simple text field (with numeric validation)
  • Read from and stored in sequence 0's page count field.
  • Option to mark page count as uncertain (with number) / unknown (no number)
  • TBD: Migrating '?' entries?

Reprints:

  • [REQ] Separate entry for "from" and "in"
  • [REQ] Separate boxes for series name, year, publisher, issue
  • [REQ] Optional box for title if it does not match
  • [REQ] Optional box for notes about how the reprint was modified (other than things already covered with credits)
  • [REQ] Will be validated against the database when saved

Credits

  • [REQ] Credits will be added/edited/deleted one at a time
    • [REQ] Existing data may be edited as a single text block
  • [REQ] Separate entry fields will be provided for:
    • [REQ] Role
      • [REQ] Select box of supported roles (localized)
        • [OPT] Extra text box for unusual roles
        • [OPT] Unusual roles may be stored in the migration column
        • TBD: how to ensure that translations of common names are always recognized, and not treated as special roles? If we do not recognize them, they cannot be re-localized in the display.
    • [REQ] Name
    • [REQ] Alias (replaces use of brackets)
    • [REQ] Signed (checkbox)
    • [REQ] Unconfirmed (checkbox- replaces use of question mark)
    • [OPT] Printed credit (checkbox)
    • [REQ] Notes (replaces use of parentheses, although many such notes are covered by roles)

Characters

  • [REQ] Characters will be added/edited/deleted one at a time
    • [REQ] Existing data may be edited as a single text block
  • [REQ] Separate entry fields will be provided for:
    • [REQ] Name
      • [REQ] Multiple names may be added, one at a time
      • [REQ] For each name, options will be present for:
        • [REQ] Name/identity used in sequence (checked by default)
        • [REQ] Primary name/identity
          • [REQ] Checked by default until a name is added with this option checked
          • [OPT] When unchecked by default, checking it prompts for confirmation that the previously marked ID should no longer be marked primary
    • [REQ] Notes (replaces use of parentheses, although the most common notes will be available as options)
    • [REQ] For each character, the following options will be available (and localized). Note that this list may be adjusted as determined by the Sr. Editors:
      • [REQ] Introduction
      • [REQ] Origin
      • [OPT] Origin retold
      • [REQ] Death
      • [OPT] Identity revealed
      • [REQ] Only in flashback
      • [REQ] Cameo
      • [REQ] Feature (TBD: What does this really mean? Is there a less confusing term?)
      • [REQ] Villain
      • [OPT] Only in dream
      • [OPT] Only in vision
    • [OPT] A checkbox marked "Alternate version?" may be checked, resulting in a text box for specifying the nature of the alternate version
    • [REQ] Group / Team
      • [REQ] Groups may be added to the record one at a time.
      • [REQ] For each group, the following options will be present:
        • [REQ] All options present for characters, with the exception of Origin and Death
        • [REQ] Formed (replaces origin)
        • [REQ] Disbanded (replaces death)
      • [REQ] A character may be added to multiple groups, one at a time
      • [REQ] For each group membership, the following options will be available (and localized)
        • [REQ] Joined
        • [REQ] Left
        • [OPT] Reserve
        • [OPT] Status unclear
Moving Records
  • The UI will include the ability to move series and issues by changing the publisher or series (respectively) to which they are attached. The change can be made along with other changes to the record in question, and approved as part of the normal process.
Cloning Sequences
  • A sequence can be cloned, which duplicates it with some or all of its data intact
    • [REQ] Clone to another issue
      • [REQ] Clone as reprint or as reprint source automatically fills in the reprint fields
    • [OPT] Clone within issue
      • TBD: What is the use case? Multi-chapter stories? Should some fields be blanked?

Approval Process

  • All changes should go through an approval process
    • Changes will be shown for approval as differences, not just as a whole new record.
    • This will make small changes very easy to identify and approve.
    • A full "Preview"-stlye view will be available for examining new records and more comprehensive changes.
    • Replacement covers will be shown alongside the cover they are replacing.
  • Further changes can only be made to approved records
  • Dependent objects may be added to pending records, but may not be approved until the parent record has been approved
    • For instance, a series may be added to a pending publisher, and issues added to the pending series. But the issues may not be approved until the series has been approved, and the series may not be approved until the publisher has been approved
    • The series and publisher (or issues and series and publisher) can be approved simultaneously
Approval Queues
  • Pending changes are sorted into queues by record types (covers, publishers [including imprints], series or issues)
  • The following actions may be taken on a pending record:
    • Approve
    • Deny (for changes verified to be flatly incorrect)
    • Return to submitter
    • Hold
      • Holding places the record in the approver's approval queue, separate from their reservation queue. This allows the approver to look into complex issues without another approver spending time on the same thing.
      • Holds are still visible in the global pending queue, but may not be acted upon by other approvers.
      • Covers are simply approved or denied, and can be selected and approved/denied in bulk
      • Covers may also be approved and marked for replacement in one step
  • Actions are applied by selecting the item or items from the queue and pressing the button, not by pressing a button for each item
  • Approvers cannot edit pending issues
    • The types of issues typically fixed by these edits should be greatly reduced, if not eliminated, by the new UI
    • Also, allowing edits within the approval process would make things much more complicated to implement
  • [OPT] Multiple issue skeletons added at once show up in the queues as one object for approval.
Queue Display

Each queue will display the following columns, as relevant (i.e. the publisher queue will not display columns for series name or issue number, etc.), and be sortable by any of them (Bugzilla-style, i.e. if you sort on column B and then re-sort on column A, it remembers column B as a secondary sort).

  • Country
  • Language
  • Publisher
  • Series name
  • Volume number
  • Issue number
  • Date Submitted
  • Submitter

Error Reporting

  • [REQ] All pages must have a link to Error Tracker (Bugzilla)
  • [REQ] All pages should have a link to the technical Bugzilla (TBD: Should we instead add a technical component to the Error Tracker? That would make end-user bug reporting much simpler. We could keep the technical Bugzilla internally.)
  • [REQ] Links should always populate the URL field with the URL of the page holding the link, except for the the front page, which should leave the field blank. Any other administrative pages should also leave the field blank.
  • [REQ] Links from pages representing publishers, series or issues should put those entities in the Summary field.
  • [REQ] Links from cover galleries should auto-select the covers component instead of the default data errors component (users can still change it).

Browser Support

Desktop browsers are the initial primary audience. Mobile browsers should be kept in mind, but may not be fully supported until a later release.

Desktop Browsers

  • [REQ] IE >= 6.0 (Windows)
  • [REQ] Firefox >= 2.0 (Windows, Mac OS, Linux)
  • [REQ] Safari >= 2.0 (Windows, Mac OS)
  • [REQ] Chrome (Windows)
  • [OPT] Opera (Windows, Mac OS, Linux)
  • [OPT] Konquerer (Linux)

Mobile Browsers

  • [OPT] Opera ?
  • [TBD: What is on iPhone, Blackberry, Treo?]

Performance

  • Comparable to the current site when it seems snappy? TBD. Need actual numbers for both simple and complex pages.
  • Caching
    • Use memcached? Hosting implications?
    • Need caching strategy (cache the whole site vs more granular strategy)

Test Infrastructure

  • [REQ] Locate or write a Selenium test driver for Django (it seems highly likely that one exists somewhere already).
  • [REQ] Classes to model the UI for Selenium tests.
    • Factor xpath or javascript access out of test code as much as possible for behavioral tests, while making the xpath clear for layout tests.
  • [OPT] Locate or write a Nose test driver (Nose is an enhancement over the built-in unittest package, and ReviewBoard includes its own Nose driver which may be of use to us).
  • [REQ] Build fixtures with data sets that load quickly enough to run the necessary tests in some reasonable amount of time. Obviously, this requirement needs some details.

Django Middleware

The following Django Middleware functionality needs to be integrated:

  • Authentication
  • Sessions
    • Stale sessions are not automatically garbage-collected, so we need to implement that, or find an available implementation.
  • Cross Site Request Forgery protection