-
Notifications
You must be signed in to change notification settings - Fork 5
Release Communications and Outreach
Draft for discussion and revision by the DCAT Interagency Maintenance Team and the Data.gov team.
This page describes the proposed release communications and outreach process for the DCAT-US v3.0 maintenance cycle.
Release communications ensure that agencies are informed about schema changes, documentation updates, deprecation notices, implementation timelines, grace periods, and available support resources.
The DCAT Interagency Maintenance Team governs schema maintenance decisions. The Data.gov team at GSA maintains the DCAT-US repository and coordinates release communications and outreach.
The purpose of release communications and outreach is to provide agencies with clear, timely, and actionable information about DCAT-US v3.0 maintenance releases.
Release communications should help agencies understand:
- What changed in a release
- Why the changes were made
- Whether changes are breaking or non-breaking
- Whether agency action is required
- When any new requirements may be enforced
- Whether a 90-day grace period applies
- Whether any deprecation notices have been issued
- Where updated documentation is available
- Where agencies can ask questions or request support
Release communications should be:
- Timely — release notes should be published within two weeks of the release tag
- Clear — agencies should be able to understand what changed and whether action is needed
- Actionable — communications should identify recommended agency actions
- Transparent — changes, deprecations, and grace periods should be documented
- Consistent — release communications should follow a repeatable format
- Accessible — agencies should know where to find documentation and where to ask questions
-
Implementation-focused — communications should explain practical impacts on metadata, validation, harvesting, and existing
data.jsonimplementations
Release communications may be shared through several channels.
| Channel | Purpose |
|---|---|
| GitHub release notes | Official release documentation associated with the tagged release |
| CDO Council channel | Broader interagency communication and awareness |
| Data.gov mailing list | Direct outreach to Data.gov and metadata stakeholders |
| DCAT Interagency Info Sharing Session | Presentation or discussion of release changes |
| DCAT Interagency Q&A Office Hours | Follow-up implementation questions from agencies |
| resources.data.gov | Updated implementation guidance, changelog, migration guidance, and related documentation |
| DCAT-US GitHub Wiki | Technical implementation FAQs and related maintenance documentation |
| datagovhelp@gsa.gov | Questions related to Data.gov harvesting or resources.data.gov documentation |
Release notes should be published within two weeks of the release tag.
Release notes should be published through:
- GitHub release notes
- CDO Council channel
- Data.gov mailing list
Release communications may also be reinforced through:
- DCAT Interagency Info Sharing Session
- DCAT Interagency Q&A Office Hours
- CDO Council touchpoints
- resources.data.gov updates
Release notes should include enough detail for agencies to determine whether the release affects their metadata implementation.
Release notes should include:
- Release version
- Release date
- Summary of changes
- Link to release tag
- Link to changelog
- Schema changes
- Documentation changes
- Bug fixes
- Enhancements
- Clarifications
- Breaking changes, if applicable
- Deprecation notices, if applicable
- Grace period information
- Migration guidance, if applicable
- Agency action items
- Links to updated documentation
- Contact information for questions
Use the following checklist when preparing release notes.
- [ ] Release version is included.
- [ ] Release date is included.
- [ ] Summary of changes is included.
- [ ] Link to GitHub release tag is included.
- [ ] Link to changelog is included.
- [ ] Schema changes are described.
- [ ] Documentation changes are described.
- [ ] Bug fixes are described.
- [ ] Enhancements are described.
- [ ] Clarifications are described.
- [ ] Breaking changes are clearly identified, if applicable.
- [ ] Deprecation notices are included, if applicable.
- [ ] 90-day grace period language is included, if applicable.
- [ ] Migration guidance is linked, if applicable.
- [ ] Agency action items are clearly identified.
- [ ] Links to updated documentation are included.
- [ ] Contact information is included.Each release tag should include a changelog entry describing all changes in the release.
The changelog should identify:
- Schema changes
- Documentation updates
- Bug fixes
- Enhancements
- Clarifications
- Deprecation notices
- Breaking changes, if applicable
- Migration guidance, if applicable
The changelog on resources.data.gov should be updated as part of the release process.
The following timeline may be used for each maintenance release.
| Timing | Activity |
|---|---|
| Before release | Prepare release notes, changelog, documentation updates, and outreach language |
| Release date | Tag release and confirm release artifacts |
| Within 2 weeks after release | Publish release notes through GitHub, CDO Council channel, and Data.gov mailing list |
| Within 2–4 weeks after release | Use DCAT Interagency Info Sharing Session or CDO Council touchpoint to discuss changes, if needed |
| During grace period | Use Q&A Office Hours to answer agency implementation questions |
| Within 30 days after release | Publish migration guidance if field-level changes affect existing data.json implementations |
| After outreach | Capture agency questions, blockers, and follow-up issues |
In some cases, agencies may need advance notice before a release.
Pre-release communications may be appropriate when:
- A breaking change is being considered
- A deprecation notice will be issued
- A change may affect existing
data.jsonimplementations - Agencies may need to update metadata generation workflows
- Agencies may need additional migration guidance
- A change may affect validation behavior
- A change may require cross-office coordination within agencies
Pre-release communications may occur through:
- Agency feedback meetings
- DCAT Interagency Info Sharing Session
- CDO Council channels
- Direct outreach to affected agencies
- GitHub issue discussion
- Draft release notes or draft deprecation notices
Post-release communications should help agencies understand the final release and determine whether action is needed.
Post-release communications should include:
- Release summary
- Link to GitHub release notes
- Link to updated documentation
- Description of agency impacts
- Description of any new requirements
- Grace period information
- Deprecation notices, if applicable
- Migration guidance, if applicable
- Instructions for asking questions
- Instructions for submitting standard-level issues
Release communications should clearly identify whether agencies need to take action.
Agency action items may include:
- Review the release notes
- Review updated implementation guidance
- Review the changelog
- Review deprecation notices
- Assess impact to existing
data.jsonfiles - Update metadata generation workflows
- Validate updated metadata files
- Submit a harvest source change request, if needed
- Attend office hours with implementation questions
- Open a GitHub issue for standard-level questions or proposed changes
If no agency action is required, the release notes should say so clearly.
Each release should include a 90-day grace period before any new requirements are enforced.
The grace period gives agencies time to:
- Review release notes
- Review updated documentation
- Assess implementation impact
- Update metadata generation processes
- Update
data.jsonfiles - Validate updated harvest sources
- Ask implementation questions
- Coordinate internally
Release communications should clearly state:
- Whether a grace period applies
- When the grace period begins
- When the grace period ends
- What agencies should do during the grace period
- Whether any enforcement or validation behavior changes after the grace period
The following language may be used or adapted in release notes.
Agencies will have a 90-day grace period before any new requirements introduced in this release are enforced. During this period, agencies should review the release notes, assess any implementation impacts, update metadata generation workflows as needed, and validate updated metadata files.
Agencies may bring implementation questions to DCAT Interagency Q&A Office Hours or contact Data.gov Help at datagovhelp@gsa.gov for questions related to Data.gov harvesting or resources.data.gov documentation.A deprecation notice should be issued when a breaking change is planned for a future release.
Deprecation notices should be included in:
- GitHub release notes
- CDO Council channel communications
- Data.gov mailing list communications
- Relevant DCAT Interagency Info Sharing Session materials
- Updated documentation, if applicable
Deprecation notices should include:
- Affected field, enum, or schema area
- Description of the planned change
- Reason for the change
- Expected release timing
- Whether the change is breaking
- Agency implementation impact
- Minimum 90-day implementation window
- Recommended agency action
- Where agencies can ask questions or provide feedback
Use the following template when preparing a deprecation notice.
# Deprecation Notice
## Affected Field or Schema Area
Describe the field, enum, object, or schema area affected by the planned change.
## Planned Change
Describe the planned change.
## Reason for Change
Explain why the change is being proposed.
## Expected Release Timing
Identify the release cycle when the change may be included.
## Impact
Describe how this may affect agency metadata, validation, harvesting, or existing `data.json` implementations.
## Agency Action
Describe what agencies should do to prepare.
## Implementation Window
Agencies will have a minimum 90-day implementation window before enforcement.
## Questions and Feedback
Agencies may ask questions through DCAT Interagency Q&A Office Hours or submit standard-level feedback through DCAT-US GitHub Issues:
https://github.com/GSA/dcat-us/issuesBreaking changes require special attention in release communications.
A breaking change is a change that may cause existing valid metadata to become invalid or require agencies to modify existing implementations.
Examples may include:
- Removing a field
- Changing an enum
- Changing a field from optional to required
- Changing allowed values
- Changing validation behavior in a way that causes previously valid records to fail
- Changing structure in a way that affects existing
data.jsonimplementations
Breaking changes require:
- Prior deprecation notice
- Minimum 90-day agency implementation window before enforcement
- Clear agency action guidance
- Updated documentation or migration guidance, if needed
- Opportunity for agency questions or feedback
Non-breaking changes may still need to be communicated clearly, even if no agency action is required.
Examples of non-breaking changes include:
- Adding a new optional field
- Updating a field description
- Clarifying usage guidance
- Correcting documentation
- Adding examples
- Fixing schema behavior that does not create breaking implementation impact
For non-breaking changes, release notes should clarify:
- What changed
- Whether agency action is required
- Whether documentation was updated
- Whether validation behavior changed
- Whether agencies may optionally adopt the change
Updated migration guidance should be published within 30 days of release if any field-level changes affect existing data.json implementations.
Migration guidance should include:
- Summary of affected fields
- Description of what changed
- Before-and-after examples, if helpful
- Recommended agency actions
- Validation considerations
- Harvesting considerations
- Timeline for agency updates
- Link to the relevant release notes or changelog
The CDO Council channel may be used to provide broader interagency awareness of DCAT-US v3.0 maintenance activity.
Communications through CDO Council channels may include:
- Release announcements
- Deprecation notices
- Grace period reminders
- Upcoming maintenance cycle reminders
- Requests for agency feedback
- Annual retrospective findings
- Links to updated documentation
- Invitations to relevant DCAT interagency meetings
The Data.gov mailing list may be used to share release information with Data.gov stakeholders, metadata contacts, and agency implementation teams.
Messages to the Data.gov mailing list may include:
- Release notes
- Summary of changes
- Links to documentation
- Grace period details
- Deprecation notices
- Office hours reminders
- Guidance on harvest source requests
- Contact information for follow-up questions
GitHub release notes serve as the official release artifact associated with the tagged release.
GitHub release notes should include:
- Release version
- Release date
- Summary of changes
- Changelog
- Links to merged pull requests
- Links to related issues
- Breaking changes, if applicable
- Deprecation notices, if applicable
- Documentation links
- Contact or support information
resources.data.gov should be updated as needed to reflect release changes.
Updates may include:
- Implementation guide updates
- Changelog updates
- Migration guidance
- Field-level documentation updates
- Example updates
- Crosswalk updates, if applicable
- Links to release notes
- Links to FAQs
The DCAT-US GitHub wiki may be updated with FAQs or technical implementation notes that arise from release questions or recurring agency issues.
FAQs may be updated based on:
- Office hours questions
- Agency feedback meetings
- GitHub issues
- Validation trends
- Harvest source transition issues
- Annual retrospective findings
Release communications should connect to existing DCAT interagency engagement forums.
Office hours may be used after a release to:
- Answer agency implementation questions
- Discuss validation issues
- Clarify field interpretation
- Help agencies understand whether action is needed
- Identify recurring questions for FAQ updates
- Identify issues that should be filed in GitHub
The monthly information sharing session may be used to:
- Present release summaries
- Demonstrate updated guidance or examples
- Walk through migration guidance
- Explain deprecation notices
- Discuss implementation patterns
- Gather agency questions and blockers
- Preview upcoming maintenance cycle topics
CDO Council touchpoints may be used to:
- Communicate governance-level changes
- Share release notes
- Discuss broader implementation impacts
- Gather agency feedback on major proposed changes
- Support the annual retrospective process
The following sample may be used or adapted for release announcements.
Subject: DCAT-US v3.0 Maintenance Release [Version Number]
The Data.gov team has published DCAT-US v3.0 maintenance release [Version Number].
Release notes are available here:
[GitHub release notes link]
Summary of changes:
- [Change 1]
- [Change 2]
- [Change 3]
Documentation updates are available here:
[Documentation link]
Agencies will have a 90-day grace period before any new requirements introduced in this release are enforced.
Agencies should review the release notes and updated documentation to determine whether any metadata, validation, or harvesting updates are needed.
Questions about DCAT-US implementation may be brought to DCAT Interagency Q&A Office Hours. Questions about Data.gov harvesting or resources.data.gov documentation may be sent to datagovhelp@gsa.gov.
Requests or issues related to the DCAT-US metadata standard may be submitted through GitHub Issues:
https://github.com/GSA/dcat-us/issuesThe following sample may be used or adapted for grace period reminders.
Subject: Reminder: DCAT-US v3.0 Release [Version Number] Grace Period
This is a reminder that DCAT-US v3.0 release [Version Number] included a 90-day grace period before any new requirements are enforced.
Grace period start date: [Date]
Grace period end date: [Date]
Agencies should review the release notes and updated documentation and make any needed metadata or validation updates before the grace period ends.
Release notes:
[GitHub release notes link]
Updated documentation:
[Documentation link]
Questions may be brought to DCAT Interagency Q&A Office Hours or sent to datagovhelp@gsa.gov for Data.gov harvesting or resources.data.gov documentation questions.The following sample may be used or adapted after agency outreach.
Subject: Follow-Up: DCAT-US v3.0 Release [Version Number]
Thank you to agencies that reviewed DCAT-US v3.0 release [Version Number] and participated in recent discussions.
Common questions and follow-up items are being tracked and may be added to the DCAT-US technical implementation FAQs:
https://github.com/GSA/dcat-us/wiki/DCAT-US-3-Technical-Implementation-FAQ
If your agency identifies a possible issue or requested change to the DCAT-US metadata standard, please submit a GitHub issue:
https://github.com/GSA/dcat-us/issues
For questions about Data.gov harvesting or resources.data.gov documentation, contact:
datagovhelp@gsa.govThe Data.gov team should track release outreach activities to confirm that communications were completed.
Outreach tracking may include:
- Release date
- GitHub release notes publication date
- CDO Council channel message date
- Data.gov mailing list message date
- resources.data.gov update date
- FAQ update date, if applicable
- Info Sharing Session date, if release was discussed
- Office hours questions received
- Agency feedback received
- Follow-up issues filed
- [ ] GitHub release notes published.
- [ ] CDO Council channel announcement sent.
- [ ] Data.gov mailing list announcement sent.
- [ ] resources.data.gov changelog updated.
- [ ] Implementation guide updated, if applicable.
- [ ] Migration guidance published, if applicable.
- [ ] FAQ updates identified or published, if applicable.
- [ ] Release discussed in DCAT Interagency Info Sharing Session, if needed.
- [ ] Office hours prepared for agency follow-up questions.
- [ ] Agency questions captured.
- [ ] Follow-up GitHub issues filed, if needed.For questions about Data.gov harvesting or resources.data.gov documentation, contact:
For requests or issues related to the DCAT-US metadata standard, use DCAT-US GitHub Issues:
https://github.com/GSA/dcat-us/issues
For implementation questions, agencies may attend DCAT Interagency Q&A Office Hours. Meeting schedule updates are posted at:
https://resources.data.gov/resources/dcat-us-3-updates/
https://github.com/GSA/dcat-us/issues
Use this issue tracker to request or discuss changes to the DCAT-US metadata standard itself.
https://github.com/GSA/dcat-us
Repository for the DCAT-US metadata standard.
https://resources.data.gov/resources/dcat-us-3-implementation/
Primary reference for agencies implementing the DCAT-US 3 metadata standard.
https://github.com/GSA/dcat-us/wiki/DCAT-US-3-Technical-Implementation-FAQ
Frequently asked questions related to technical implementation of the DCAT-US 3 metadata standard are posted here as they are developed.
https://resources.data.gov/resources/dcat-us-3-updates/
Use this page for meeting schedule updates and related DCAT-US 3 engagement information.
Use this contact for questions about Data.gov harvesting or resources.data.gov documentation.
- DCAT-US 3 Implementation Resources
- Agency Workflow for DCAT-US 3 Harvest Source Requests
- Inventory.data.gov Access
- Harvest Source Review and Validation
- Harvest Source Change Requests
- FAQ Overview
- DCAT-US 3 Technical Implementation FAQ
- Harvest Source Request FAQ
- Inventory.data.gov Access FAQ
- Meeting FAQ
- Tracking and Issue Routing FAQ
- DCAT Interagency Maintenance Team
- DCAT IMT CHARTER
- Maintenance Process Overview
- Roles and Responsibilities
- Issue Triage and GitHub Workflow
- Semi-Annual Release Cycles
- Agency Feedback and Participation
- Release Communications and Outreach
- Annual Retrospective
- Maintenance Meeting Schedule
- Maintenance Templates