How hmrc/income-tax-mtd-changelog works
Project Type and Purpose
• This is not an application or library but a documentation/changelog repository for the “Making Tax Digital for Income Tax APIs.”
• It contains markdown files (the README, mapping instructions, notification guide) plus CSVs for tax‐form mappings, and a repository.yaml that likely drives the static site generator or publishing pipeline.
File Structure Analysis
– Top-level:
• .github/ISSUE_TEMPLATE.md – GitHub issue templates
• .gitignore, LICENSE, README.md – standard docs
• repository.yaml – configuration for site generation or CI/CD
– mapping/mapping-csv-files.md – docs explaining the CSVs
– notifications/get-notified.md – instructions for subscribing to change notifications
README Insights
• Describes the purpose: a chronological changelog of API version updates, deprecations, new endpoints, error changes, etc.
• Points readers to two ancillary docs: “get-notified” and “mapping-csv-files.”
• No runtime code or services, but implicitly this repo feeds a documentation website (e.g., HMRC Developer Hub or GitHub Pages).
Main Components
A. Content Sources (Markdown + CSV)
B. Site Generation Pipeline (Static Site Generator + CI/CD)
C. Repository (GitHub)
D. Hosting/Publishing Platform (e.g., GitHub Pages or HMRC Developer Hub)
E. End Users (Developers consuming docs)
F. External Notifications Service (e.g., email/webhook subscriber system)
Relationships and Interactions
• Authors commit markdown/CSV changes → GitHub repo
• GitHub Actions (CI) triggered on push → reads repository.yaml + content → Static Site Generator builds HTML/JS/CSS
• Build artifacts deployed to hosting platform (GitHub Pages/CDN or HMRC portal)
• End users browse the published site; may subscribe via instructions in notifications to an external notification service or webhook
• CSVs drive sections of the site (mapping pages) by being parsed at build time
Architectural Patterns and Principles
• “Content as Code”: docs and data live alongside CI config in version control
• Static Site Generation (SSG) pattern for low-latency, secure, easily cacheable output
• Continuous Delivery: automated build & deploy via GitHub Actions
• Clear separation:
• Source layer (content repo)
• Build layer (CI + generator)
• Delivery layer (hosting/CDN)
Technologies and Frameworks
• GitHub & GitHub Actions for version control and CI/CD
• Static site generator (e.g., Jekyll, Hugo, Middleman – implied by repository.yaml)
• Hosting (GitHub Pages or custom HMRC Developer platform)
• CSV parsing plugin/module in the SSG to render mapping tables
Essential Elements to Capture
• Content sources: mapping/, notifications/, README.md
• Configuration: repository.yaml, .github/workflows/…
• Static Site Generator step (parses markdown + CSV)
• Continuous Deployment via GitHub Actions
• Hosting platform (CDN, GitHub Pages or HMRC Developer Hub)
• Developer/Consumer interaction and subscription mechanism
Final Recommendations
• Within Source, show GitHub Repo containing Markdown + CSV + YAML.
• In Build, show GitHub Actions running SSG (tools/plugins).
• In Delivery, show hosted site on CDN/Developer Hub and the Notifications service.