Need Guidelines for Contributors, concerning Issues

[rwschwanke]

Guidelines for Issues

We manage issues by attaching tags ("labels") to them. For example,

The Happy Path

1. New Issue
   1. Write description
   2. Optional: add screen shot(s) if helpful
   3. Add a Type tag
   4. Add a Priority tag
   5. Add Pages tag(s)
   6. Add subsystem tag(s)
2. Open Issue
3. Assign issue to a developer
4. Developer adds In Progress tag when s/he begins actively working on the issue.
5. All can make comments
6. All can revise tags
7. Developer adds a test case that can be executed from a client UI.
8. Developer adds a resolution tag
9. Developer replaces in-progress with pending merge tag
10. When code resolving the issue is merged into the test system, someone replaces pending merge with in-test tag and assigns issue to a tester.
11. Tester confirms resolution, removes in-test and Closes the issue.

    General Remarks

    • An issue can be almost anything that is worth tracking, from a bug to a new idea to a customer request.
    • Feel free to insert screen shots; they help a lot.
    • For bugs, please provide instructions for reproducing the bug.
    • For issues raised by non-developers, please include
    • the original text AND
    • your "translation" into what it means for developers.

      Changing the subject

If you uncover a new issue while resolving an existing one, you have two choices:

• if the new issue completely replaces or subsumes the old one, you can change the title and description of the issue to reflect it, and revise the tags accordingly.
• if the old issue has had a significant life of its own, please create a new issue rather than rewriting the old one.

  Priority Tags (Red or pink)

These are listed in decreasing order of priority.

Blocking This issue is preventing another major-priority issue from being addressed. Critical This issue could cause serious long-term damage to the reputation of the software or its developers. Major The software cannot be used productively until this issue is resolved. Minor The software will be inconvenient to use until this issue is resolved Trivial Many users will not notice that this issue has not been resolved. Deferred This issue is being ignored until the next development cycle.

Type Tags (green)

What kind of an issue is it?

bug The software does not behave as intended or expected. enhancement The issue proposes an improvement to an existing feature. feature The issue defines a user-visible feature. task The developers should do this thing, even though it is not a bug, feature, or enhancement. question Does this need a definition? content The wording, URLs, images, or graphics on a web-page are wrong, but do not affect the correct functioning of the software. [epic], [story] TBD

Pages tags (Lavender)

Which client web pages are involved in the issue?

Dataset Page describing one Collection ("Dataset") -details A separate page providing more details for part of its parent page, e.g. Dataset-details Harvest The page on the central, "NGDS" client where one collects data from the NODEs. Home The home page on either NGDS or NODE. Library The page supporting faceted search and returning only textual results. Map The page that displays the geospatial span of result datasets on a world map. Resources A page describing and linking to resources and tools available to the public for analyzing the NGDS data. Un/Publish TBD

subsystem tags (dark blue)

Which server components are involved in the issue?

bulk-upload ckan content-model datastore geoserver ogc setup TBD: solr, fulltext, spatial, postgres

Status Tags (light blue)

Github classifies an issue as either Open or Closed. The following tags are normally only used for Open issues; if found on a Closed issue, it should normally be re-opened.

check tags The status of the issue is unclear because the tags might not correctly characterize it. in-progress The issue is assigned to someone and that person is attempting to analyze and resolve it. pending merge The issue implementation has not yet been merged into the test system. in-test The issue has been tentatively resolved, but has not yet been independently tested.

Resolution tags

When a developer has finished analyzing an issue and attempting to resolve it, s/he adds one of the following tags:

fixed The issue has been adequately resolved (bug fixed, feature implemented, question answered, data repaired, etc.) duplicate The issue more-or-less duplicates another issue. Its content has been incorporated into the other issue. invalid As written, the issue is not true, not relevant, out of scope, or otherwise invalid. If the author feels strongly about it, s/he should confer, rewrite, and resubmit as a new issue. wontfix Although the issue is valid, it won't be fixed. defer The issue will not be addressed in the current development cycle.

Cross-cutting Attribute tags (Gold)

These tags are created as needed to represent attributes that cross-cut the other categories:

GTO Finding The issue has been reported by the Geothermal Technology Office or others in the DOE Geodata Quality The issue is related to incorrect or incorrectly reported geothermal meta-data. NGDS The issue is specific to the NGDS (central) installation. NODE The issue is specific to a Node-in-a-Box installation. Date Reference in title Any Gold tag whose name references a date identifies issues relevant to a meeting, milestone, or other event happening on that date. Recovery The issue pertains to robust recovery from errors, whether those errors pertain to bugs, bad data, user mistakes, or whatever. Selenium The issue involves the Selenium test automation tool. UX The issue pertains to user experience or user interface design.

[rwschwanke]

@chkhm @rtanikella please review before installing

[rwschwanke]

I will create the Wiki page first. then Raj will create a Guidelines page that leads the contributor from the Issues list to the Wiki page.

[smrgeoinfo]

This is now on the Wiki, close here