Issue Labels

Issue labels

Issues can be given a number of different labels, in the following categories. All issues should be given one type label. Other labels are optional.

type

This label defines what type of issue it is; all issues should be given one of these type labels. We give an issue just a single type label, based on the best fit for that issue.

• Issues requiring code (or documentation) changes

  • type: bug: Something is working incorrectly. This may cause incorrect science results - in which case it should also be given the tag: bug - impacts science label - or may have some other impact, such as the model crashing. If this causes significant problems in important model configurations, the issue should also be given the tag: bug - critical label.

  • type: code cleanup: Code changes whose primary purpose is to improve the internal code structure (i.e., refactoring). These may result in behavior changes (e.g., answer changes due to reordering calculations), but these behavior changes are incidental rather than the main purpose of the code changes. This can also include additions or edits needed in code comments.

  • type: documentation: Additions or edits needed in user-facing documentation. This includes the user's guide, tech note, wiki, README files, and xml files. In most cases, issues with this label have no impact on the running of the code and should not require testing. However, this is not always the case: for example, changes in xml files require at least some testing.

  • type: enhancement: Code additions/modifications that bring in new capabilities or improve the behavior of existing capabilities. The changes can be of a scientific or purely software (e.g., user interface) nature; if this involves major new science, the issue should also be given the tag: en - major new science label. Note that, if the issue mainly involves changing internal code structure rather than external behavior, it should be given the type: code cleanup label rather than this one.

  • type: tests: Additions or changes to tests (either unit tests or system tests). (Other issue types, such as enhancements, often involve adding tests as well. Issues with the type: tests label are just about adding/changing tests.)

• Issues not requiring code (or documentation) changes (at least, not initially: e.g., a "discussion" or "needs investigation" issue could lead to the need for changes later) (note: these labels have a prefix of - simply to force them to all appear together in GitHub's alphabetic sorting)

  • type: -discussion: This issue's resolution involves discussion within the github issue page.

  • type: -investigation: A task that involves some investigation. For example, this could involve performance evaluations. As opposed to type: discussion, there will often be significant work needed to close this issue. Once this is resolved, other issues (enhancements or bugs) may be opened based on the findings.

  • type: -support: A user or developer has run into trouble or needs support with getting something to work.

priority

This label describes where this issue should fall on the priority list - i.e., whether it should be addressed soon, or whether it can wait for a while. Issues not given a priority label implicitly have a medium priority.

• priority: high: This issue should be addressed soon

• priority: low: This issue can be deferred for a while

blocked

This label describes various reasons why an issue can't be dealt with immediately. We can periodically review issues with these labels to see if the condition blocking a given issue no longer applies.

• blocked: answer changing: This issue would be relatively easy to resolve, but we are waiting to resolve it until we can accept answer changes on master. (Note: many answer-changing issues will NOT have this label; this is mainly used for issues for which the only thing stopping us from fixing it right away is that it changes answers.)

closed

These labels can be applied to issues that are closed without being fixed.

• closed: duplicate: This issue is a duplicate of another issue. The duplicate issue number should be noted in an issue comment.

• closed: invalid: This is not really an issue. For example, someone may have thought there was a bug, but in fact the code is operating as intended or there was user error.

• closed: moved: This is an issue with some other component, so the issue has been moved to a different repository.

• closed: wontfix: We have decided not to fix this bug, not to implement this enhancement, etc.

tag

These are miscellaneous labels that can be applied to any issue to help people find certain classes of issues later.

• tag: bug - critical: This tag can be applied to bugs, and means that this bug causes significant problems in important model configurations.

• tag: bug - impacts science: This tag can be applied to bugs, and means that this bug causes significantly incorrect results in the model's science, at least in some configurations. Bugs that cause the model to crash are not given this label: this is reserved for problems where the model runs but gives incorrect results (which is often worse than crashing).

• tag: en - major new science: This tag can be applied to enhancements, and means that this enhancement brings in major new science capabilities.

• tag: good first issue: This would be a good issue for someone who is just starting to contribute to CTSM.

• tag: lilac: This issue is for the sake of the LILAC project (https://github.com/NCAR/lilac)

• tag: simple bfb: This issue should be relatively easy to fix and should not change answers for any configuration (i.e., it is bit-for-bit). Therefore, it is a good candidate for being combined with other bit-for-bit issues in running the test suite.

• tag: support tools only: Code changes that only affect auxiliary support tools, without affecting the main CTSM code or the standard input file support chain. This would include tools in the "contrib" directory as well as other auxiliary tools that don't have standard tests and are not used as part of normal operation of either CTSM or the creation of surface datasets. For example, this includes refactor tools, tools to create lists of input files for XML, etc.

Some good starting points for issue searches

Not in a project and not low priority

This is a good starting point for issues that should be reviewed regularly. Issues in projects are excluded under the assumption that projects have their own prioritization / triaging process.

is:issue is:open -label:"priority: low" no:project

No type label

All issues should have a type label. Those that don't may be missed in issue reviews.

is:issue is:open -label:"type: -discussion" -label:"type: -investigation" -label:"type: -support" -label:"type: bug" -label:"type: code cleanup" -label:"type: documentation" -label:"type: enhancement" -label:"type: tests"