Issue Labels

Issues can be given a number of different labels, in the following categories. All issues should be given a 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. Note that the assignment of these labels can be somewhat subjective - e.g., the difference between type: bug - impacts science and type: bug - other. We do our best to assign the most appropriate label, but can't guarantee that (for example) all known bugs that affect the science of a particular configuration of interest are labeled with type: bug - impacts science.

• Issues requiring code (or documentation) changes

  • type: bug - impacts science: Something is working incorrectly. This causes significantly incorrect results in the model's science, at least in some configurations.

  • type: bug - other: Something is working incorrectly. This does not cause incorrect results in the model's science, but has some other impact, such as the model crashing. (Or this may produce slightly incorrect results in some diagnostic fields, but doesn't have a significant scientific impact.)

  • type: code cleanup/docs: 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 also includes additions or edits needed in in-code documentation (comments in Fortran code, python code, xml files, etc.: any file whose changes require testing, in contrast to type: docs - non-code).

  • type: enhance - science: New science capabilities or additions/modifications to existing science capabilities. In contrast to type: enhance - software, an issue with this label will require some science development.

  • type: enhance - software: Code additions/modifications that involve some change in behavior, but do not require science development. The behavior changes are the primary purpose here, in contrast to type: code cleanup/docs, where any behavior changes are incidental rather than the main purpose.

  • type: tests: Additions or changes to tests (either unit tests or system 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)

  • type: support tools: Code changes that only affect auxiliary support tools, without affecting the main CTSM code nor 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 nor used as part of normal operation of either CTSM or the creation of surface datasets. So for example refactor tools, or tools to create lists of input files for XML etc.

  • type: docs - non-code: Additions or edits needed in non-code documentation. This includes the user's guide, tech note and wiki. Issues given this label should have no impact on the running of the code, and should not require testing. This label can be used for other things that are not strictly documentation-related but have no impact on the running of the code, such as changing .gitignore files.

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

  • type: needs 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 needed: 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

severity

This label describes the impact of the issue. This is typically applied to bugs. Issues without a severity label have a normal or low severity.

• severity: critical: This issue causes significant problems in important model configurations.

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: good first issue: This would be a good issue for someone who is just starting to contribute to CTSM.

• tag: help wanted: The CTSM core team would love help from the community on this issue.

• 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.