Several groups mark the SQuaSH and Sasquatch streams with annotations on events of interest (usually Jira issues being merged to
main). This page keeps track of the agreed conventions for these annotations.
Context and Purpose
There are 3 main meetings in which annotations are entered or prepared for. Entering an annotation is a way to communicate changes to others. Tags are a way to LIMIT the changes communicated to others. e.g. Pipeline=AP means that the annotator thinks it only applies to the AP Pipeline. Dataset=DECam means that the annotator thinks that this change ONLY applies to DECam. For example at the DRP Metrics Meeting, we will filter on Pipeline != AP and Dataset != DECam
All annotations should include the Jira issue label. They may include a brief summary of what the relevant change was.
Some AP annotations are marked with the time of the merge commit, while others are marked with the time of the processing run that showed a change in behavior. The latter approach should not be used for annotations that apply to multiple pipelines (see below), because the pipelines are not run at the same time.
We use the following tags for annotations. These tags have been agreed by representatives of the AP, DRP, and V&V teams.
Pipeline: the pipeline to which an event (e.g., code change) applies. Leave this tag unset for events that apply to all pipelines. Current values:
Instrument: the short name of the instrument to which an event (e.g., updated configs) applies. Leave this tag unset for events that apply to processing of data from any instrument. Current values:
Dataset: the dataset to which an event (e.g., updated calib/template data) applies. Leave this tag unset for events that are not dataset-specific (including anything that would affect all data processed with a given instrument; some older annotations misuse
Datasetfor this). Current values:
Gen(SQuaSH only): the pipeline/middleware generation to which an event applies. This tag may be omitted for new annotations, but is useful historically. Leave this tag unset for events that affect any framework. Current values:
We do not recommend using tags to represent aspects of an annotated event that are unique to that event, such as configuration settings or specific packages/components changed, as this information will never be filtered on (see "Context and Purpose", above) and clutters up the filter UI for other users. Such information is better provided in the annotation text.
The current tagging system makes it difficult to filter annotations for all those of interest to a particular group. For example, DRP would want all DRP annotations and all pipeline-independent annotations. The only way to express this in the current system is the conjunction
Pipeline != AP ,
Pipeline != hsc , which will break as more values are added to the tag (I have verified that unset tags count as "not equal" in this context).