Overview

We use GitHub to track development.

To learn about GitHub, it is worth taking some time to read through the FAQ. When in doubt, the first step is to click the "Help" button at the top of the page.

• To address specific people, use a github feature called "@mentions" e.g. write @dlebauer, @robkooper, @mdietze, or @serbinsh ... in the issue to alert the user as described in the GitHub documentation on notifications

Bugs, Issues, Features, etc.

Reporting a bug

1. (For developers) work through debugging (see debugging wiki).
2. Once you have identified a problem, that you can not resolve, you can write a bug report
3. Write a bug report
4. submit the bug report
5. If you do find the answer, explain the resolution (in the issue) and close the issue

Required content

Note:

• a bug is only a bug if it is reproducible

• clear bug reports save time

• Clear, specific title

• Description -
  • What you did
  • What you expected to happen
  • What actually happened
  • What does work, under what conditions does it fail?
  • Reproduction steps - minimum steps required to reproduce the bug
• additional materials that could help identify the cause:
  • screen shots
  • stack traces, logs, scripts, output
  • specific code and data / settings / configuration files required to reproduce the bug
  • environment (operating system, browser, hardware)

Requesting a feature

(from The Pragmatic Programmer, available as ebook through UI libraries, hardcopy on David’s bookshelf)\

• focus on “user stories”, e.g. specific use cases

• Be as specific as possible,

• Here is an example:

  1. Bob is at www.mysite.edu/maps
  2. map of the the region (based on user location, e.g. US, Asia, etc)

  3. option to “use current location” is provided, if clicked, map zooms in to, e.g. state or county level

     1. for site run:

        1. option to select existing site or specify point by lat/lon
        2. option to specify a bounding box and grid resolution in either lat/lon or polar stereographic.

     2. asked to specify start and end times in terms of year, month, day, hour, minute. Time is recorded in UTC not local time, this should be indicated

Closing an issue

1. Definition of “Done”
   • test
   • documentation
2. when issue is resolved:
   • status is changed to “resolved”
   • assignee is changed to original author
3. if original author agrees that issue has been resolved
   • original author changes status to “closed”
4. except for trivial issues, issues are only closed by the author

When to submit an issue?

Ideally, non-trivial code changes will be linked to an issue and a commit.

This requires creating issues for each task, making small commits, and referencing the issue within your commit message. Issues can be created on GitHub. These issues can be linked to commits by adding text such as fixes gh-5 (see [[Using Git During Development|Using-Git#during-development]]).

Rationale: This workflow is a small upfront investment that reduces error and time spent re-creating and debugging errors. Associating issues and commits, makes it easier to identify why a change was made, and potential bugs that could arise when the code is changed. In addition, knowing which issue you are working on clarifies the scope and objectives of your current task.

Label Categories