Skip to content

Issue Triage and GitHub Workflow

Jump to bottom
Susan Valente edited this page Aug 28, 2026 · 2 revisions

Issue Triage and GitHub Workflow

Draft for discussion and revision by the DCAT Interagency Maintenance Team and the Data.gov team.

This page describes the proposed issue triage and GitHub workflow for maintaining the DCAT-US v3.0 metadata standard.

The purpose of this workflow is to provide a clear, transparent, and repeatable process for:

  • Submitting issues or change requests
  • Classifying issues
  • Routing issues to the appropriate process
  • Assigning issues to maintenance milestones
  • Reviewing issues during release cycles
  • Documenting decisions
  • Preparing approved changes for pull requests and release

The DCAT Interagency Maintenance Team governs schema maintenance decisions. The Data.gov team at GSA maintains the DCAT-US repository and coordinates issue triage and maintenance cycle logistics.

GitHub Issue Tracker

Requests or issues related to the DCAT-US metadata standard should be submitted through the DCAT-US GitHub Issues page:

DCAT-US GitHub Issues:
https://github.com/GSA/dcat-us/issues

Use this issue tracker for:

  • Requests to change the DCAT-US metadata standard
  • Proposed updates to fields, definitions, usage notes, or requirements
  • Schema bugs or inconsistencies
  • Questions about schema intent or behavior
  • Standard-level metadata modeling considerations
  • Suggested improvements to DCAT-US documentation or guidance

Continuous Issue Triage

Issues are triaged on a rolling basis as they are submitted, rather than batched to a specific time of year.

The Data.gov team applies a classification label to each new issue within two weeks of submission.

Issue Labels

Each new issue should receive one of the following classification labels.

Label Meaning
bug The schema behaves incorrectly or inconsistently with the specification
enhancement A proposed addition or improvement to the schema
question A request for clarification on schema intent or behavior

Label: bug

Use the bug label when the issue describes schema behavior that is incorrect, inconsistent, or not aligned with the specification.

Examples may include:

  • The schema validates something that should not be valid
  • The schema rejects something that should be valid
  • A field behaves inconsistently with documented requirements
  • A schema rule conflicts with the implementation guide
  • A validation behavior appears inconsistent with schema intent

Label: enhancement

Use the enhancement label when the issue proposes an addition or improvement to the schema.

Examples may include:

  • Adding a new optional field
  • Improving a field definition
  • Updating usage guidance
  • Clarifying allowed values
  • Improving schema structure
  • Proposing support for an implementation pattern not currently covered

Label: question

Use the question label when the issue asks for clarification about schema intent, behavior, field interpretation, or implementation expectations.

Examples may include:

  • How should a field be interpreted?
  • Is a specific metadata pattern allowed?
  • What is the intended behavior for a field?
  • How should agencies handle a particular edge case?
  • Does a specific implementation approach align with DCAT-US v3.0?

Issue Sources

Issues may come from several sources.

Direct GitHub Submissions

Anyone may open an issue directly in the DCAT-US GitHub repository:

https://github.com/GSA/dcat-us/issues

Zendesk or Data.gov Help Channels

Some issues may first be received through Data.gov support channels, including:

datagovhelp@gsa.gov

If a question or request is related to the DCAT-US metadata standard and is not already represented as a GitHub issue, the Data.gov team may cross-file the issue in GitHub.

CDO Council or Interagency Channels

Issues may also be raised through:

  • CDO Council channels
  • DCAT Interagency Q&A Office Hours
  • DCAT Interagency Info Sharing Sessions
  • Agency feedback meetings
  • Release outreach discussions
  • Annual retrospective discussions

If an issue raised through these channels is related to the DCAT-US metadata standard and is not already on GitHub, the Data.gov team may cross-file the issue.

Harvesting, Validation, or Documentation Review

Issues may also be identified through:

  • Harvest validation error trends
  • New Relic data review
  • Documentation audits
  • Example validation
  • Agency harvest source transition work
  • Data.gov implementation review

If these issues indicate a schema clarification, documentation gap, or possible standard-level change, the Data.gov team may file or cross-file a GitHub issue.

What Belongs in DCAT-US GitHub Issues

Use the DCAT-US GitHub Issues page for standard-level DCAT-US issues.

Appropriate issues include:

  • Requesting a change to the DCAT-US metadata standard
  • Proposing updates to DCAT-US fields, definitions, usage notes, or requirements
  • Raising questions about schema structure or interpretation
  • Identifying inconsistencies, ambiguities, or gaps in the standard
  • Discussing standard-level metadata modeling considerations
  • Suggesting improvements to DCAT-US documentation or guidance
  • Raising questions about whether schema behavior aligns with the specification

What Does Not Belong in DCAT-US GitHub Issues

Some issues should use other processes.

Issue Type Use This Process Instead
Request a new DCAT-US 3 harvest source Harvest Source Change Request Form
Request a change to an existing harvest source Harvest Source Change Request Form
Track harvest source request status Harvest Source Management Board
Report Data.gov product bugs, enhancements, or defects Data.gov Team Board
Request or renew Inventory.data.gov access Inventory.data.gov Access Request Form
Ask a general Data.gov harvesting support question datagovhelp@gsa.gov
Ask an implementation question for discussion DCAT Interagency Q&A Office Hours

Triage Workflow

The following workflow describes how issues are processed after submission.

Step 1: Issue Is Submitted or Cross-Filed

An issue may be:

  • Opened directly in the DCAT-US GitHub repository
  • Cross-filed by the Data.gov team from Zendesk
  • Cross-filed by the Data.gov team from CDO Council channels
  • Cross-filed based on office hours or interagency discussions
  • Cross-filed based on documentation review or validation trend analysis

Step 2: Data.gov Team Reviews the Issue

The Data.gov team reviews each new issue within two weeks of submission.

During initial review, the Data.gov team determines:

  • Whether the issue is in scope for DCAT-US v3.0 maintenance
  • Whether the issue is a bug, enhancement, or question
  • Whether the issue is schema-related, documentation-related, implementation-related, or out of scope
  • Whether the issue is time-sensitive
  • Whether the issue needs more information
  • Whether the issue should be routed to another process

Step 3: Data.gov Team Applies a Classification Label

The Data.gov team applies one of the following labels:

  • bug
  • enhancement
  • question

Additional labels may be added if helpful for repository management, such as:

  • documentation
  • needs more information
  • breaking change
  • non-breaking
  • security considerations
  • future cycle

Any additional labels should support triage, review, or release planning.

Step 4: Issue Is Routed or Assigned

After classification, the issue may be:

  • Assigned to a maintenance cycle milestone
  • Left in the backlog for future consideration
  • Referred to the DCAT Interagency Maintenance Team for review
  • Routed to the Data.gov Team Board
  • Routed to the Harvest Source Management process
  • Converted into a documentation task
  • Converted into an FAQ or implementation guidance update
  • Marked as needing more information
  • Closed if out of scope or otherwise resolved

Step 5: Issue Is Assigned to a Milestone, If Appropriate

Issues approved for upcoming release consideration are assigned to the corresponding milestone.

Examples:

  • Cycle 1 Spring Release
  • Cycle 2 Summer Release
  • Future Maintenance Cycle
  • Backlog

Milestones help organize issues for review during the semi-annual maintenance cycle.

Step 6: DCAT Interagency Maintenance Team Reviews Prioritized Issues

During each release cycle, the DCAT Interagency Maintenance Team reviews prioritized issues in the relevant milestone.

The team considers:

  • Issue type
  • Implementation impact
  • Whether the change is breaking or non-breaking
  • Whether the change affects validation
  • Whether the change affects existing data.json implementations
  • Whether documentation or migration guidance is needed
  • Whether agency feedback is needed
  • Whether a deprecation notice is required
  • Whether a 90-day implementation window is required

Step 7: Issue Disposition Is Assigned

The DCAT Interagency Maintenance Team assigns a disposition to each reviewed issue.

Disposition Meaning
Approved for PR The issue should move forward as a pull request
Deferred The issue should be reconsidered in a future cycle
Closed as won’t fix The issue will not be addressed through a schema or documentation change
Needs more information Additional information is needed before a decision can be made
Documentation update only The issue should be addressed through documentation, examples, FAQs, or guidance rather than a schema change

Step 8: Pull Request or Documentation Work Is Created

If an issue is approved for PR, the Data.gov team, Schema Team, or designated contributor opens a pull request.

If the issue is documentation-related, a documentation task is created or assigned.

If the issue is a recurring implementation question, it may be added to:

  • DCAT-US technical implementation FAQs
  • resources.data.gov guidance
  • Meeting agenda for office hours or information sharing sessions
  • Future implementation guidance

Step 9: Review and Release

Approved changes are reviewed and prepared for release according to the semi-annual release cycle.

Release activities may include:

  • Pull request review
  • Schema review
  • Security considerations review, if applicable
  • Documentation update
  • Example validation
  • Changelog update
  • Release note drafting
  • Release tagging
  • Agency outreach

Breaking and Non-Breaking Changes

During issue review, the team should determine whether a proposed change is breaking or non-breaking.

Non-Breaking Changes

Non-breaking changes may be included in the next release cycle if approved.

Examples include:

  • Adding a new optional field
  • Updating a field description
  • Clarifying usage guidance
  • Correcting documentation
  • Adding examples
  • Fixing schema behavior that is inconsistent with the specification, if the fix does not create a breaking implementation impact

Breaking Changes

Breaking changes require prior notice and a minimum 90-day agency implementation window before enforcement.

Examples may include:

  • Removing a field
  • Changing an enum
  • Changing field requirements in a way that affects existing implementations
  • Changing validation behavior in a way that causes previously valid records to fail

Breaking changes approved in Cycle 1 are deferred to Cycle 2 at the earliest, with a deprecation notice issued in Cycle 1 outreach.

Change Type Rules

Change Type Example Earliest Release Notice Required
Non-breaking addition New optional field Next cycle None
Non-breaking clarification Updated field description Next cycle None
Breaking change Removed field, changed enum Cycle after notice Deprecation notice in prior cycle outreach

Security Considerations

Schema changes touching any of the following fields must include a security considerations note in the pull request:

  • accessRestriction
  • useRestriction
  • cuiRestriction

The security considerations note should explain:

  • What field is affected
  • What behavior is changing
  • Whether the change affects agency implementation
  • Whether the change affects validation
  • Whether the change could affect representation of access, use, or CUI-related restrictions
  • Any recommended agency review or implementation considerations

Suggested GitHub Issue Template

The following template may be used or adapted for DCAT-US GitHub issues.

Issue Type

Select one:

  • Bug
  • Enhancement
  • Question

Summary

Briefly describe the issue, proposed change, or question.

Affected Field or Schema Area

List the affected field, object, enum, or schema area, if applicable.

Description

Provide details about the issue or proposed change.

Example

Include example metadata, validation output, or implementation behavior, if available.

Expected Behavior

Describe what you expected to happen.

Actual Behavior

If this is a bug, describe what happened instead.

Implementation Impact

Describe how this affects agency implementation, validation, harvesting, documentation, or existing data.json files.

Is This Time-Sensitive?

  • Yes
  • No

If yes, explain the timing need.

Suggested Resolution

Optional: describe a proposed resolution, clarification, or change.

Additional Context

Add links, screenshots, related issues, or other context.

Suggested Pull Request Checklist

The following checklist may be used for schema-related pull requests.

Pull Request Checklist

  • Linked to a GitHub issue.
  • Issue disposition is documented.
  • Change type has been identified.
    • Non-breaking addition
    • Non-breaking clarification
    • Breaking change
  • Breaking change notice requirements have been considered.
  • 90-day agency implementation window has been considered, if applicable.
  • Documentation updates are included or linked.
  • Example records have been validated, if applicable.
  • Changelog entry is included or drafted.
  • conformsTo URI impact has been considered.
  • Security considerations note is included if the change touches:
    • accessRestriction
    • useRestriction
    • cuiRestriction

Routing Examples

Example 1: Agency Requests a New Harvest Source

An agency wants Data.gov to add a new DCAT-US 3 harvest source.

This should not be filed as a DCAT-US GitHub issue.

Use the Harvest Source Change Request Form:

https://touchpoints.app.cloud.gov/touchpoints/ffb7e9d0

Example 2: Agency Wants to Change a Field Definition in the Standard

An agency proposes changing a DCAT-US field definition or usage note.

This should be submitted as a DCAT-US GitHub issue:

https://github.com/GSA/dcat-us/issues

Example 3: Agency Finds a Data.gov Harvester Bug

An agency identifies a possible defect in how the Data.gov Harvester processes metadata.

This should be tracked through the Data.gov Team Board or routed through Data.gov support:

https://github.com/orgs/GSA/projects/11/views/1

Questions may also be sent to:

datagovhelp@gsa.gov

Example 4: Agency Needs Inventory.data.gov Access

An agency needs access to Inventory.data.gov to create a DCAT-US 3 compliant file.

Use the Inventory.data.gov Access Request Form:

https://touchpoints.app.cloud.gov/touchpoints/9145dd7e

Example 5: Agency Has a Question About Field Interpretation

An agency has a question about how to interpret a DCAT-US 3 field.

The agency may:

Review the DCAT-US 3 Implementation Guide. Review the DCAT-US technical FAQs. Bring the question to DCAT Interagency Q&A Office Hours. Open a DCAT-US GitHub issue if the question identifies a potential issue or requested change to the standard.

DCAT-US 3 Implementation Support

Meetings

Implementation Resources

Data.gov Team Process

FAQs

Reference

DCAT Interagency Maintenance Team

Clone this wiki locally