Skip to content

Commit 19bf2b3

Browse files
Copilotjkiddo
Copilot
and
jkiddo
authored
Add .github/copilot-instructions.md for agent onboarding (#195)
* Initial plan * Add comprehensive .github/copilot-instructions.md file Co-authored-by: jkiddo <211696+jkiddo@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jkiddo <211696+jkiddo@users.noreply.github.com>
1 parent b2a5c9e commit 19bf2b3

File tree

1 file changed

+257
-0
lines changed

1 file changed

+257
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
# DK Core - Copilot Instructions
2+
3+
## Repository Overview
4+
5+
**DK Core** is a FHIR Implementation Guide (IG) for Denmark, defining core FHIR profiles, extensions, code systems, and value sets for use across Danish healthcare sectors. This repository is maintained by HL7 Denmark and serves as the foundational specification for Danish FHIR implementations.
6+
7+
- **Type**: FHIR Implementation Guide
8+
- **Language**: FSH (FHIR Shorthand) + Markdown documentation
9+
- **Size**: ~1.8MB (25 FSH files, ~4,300 lines of FSH code)
10+
- **Primary Tools**: HL7 FHIR IG Publisher (Java-based), FSH (embedded in publisher)
11+
- **FHIR Version**: 4.0.1
12+
- **Dependencies**: hl7.fhir.uv.phd (1.1.0), hl7.fhir.uv.ipa (1.0.0)
13+
14+
## Key Repository Information
15+
16+
### What This Repository Does
17+
- Defines Danish core FHIR profiles (Patient, Organization, Practitioner, Observation, etc.)
18+
- Provides Danish-specific extensions, code systems, and value sets
19+
- Includes CPR (Danish civil registration), SOR (healthcare organization registry), and other Danish identifiers
20+
- Offers both standard DK profiles and IPA-compliant profiles for patient-facing applications
21+
- Published at http://hl7.dk/fhir/core/ and https://hl7dk.github.io/dk-core/
22+
23+
### Primary Governance
24+
- Approved by HL7 Denmark
25+
- Regularly reviewed by Danish FHIR SIG (meets every odd week on Mondays 15:00-16:00)
26+
- Submitted to Danish Health Data Authority after HL7 Denmark approval
27+
28+
## Build and Validation Process
29+
30+
### Prerequisites
31+
- **Java**: OpenJDK 17+ required (tested with OpenJDK 17.0.17)
32+
- **Memory**: At least 3.5GB RAM for Java heap
33+
- **Internet**: Required for downloading publisher and terminology server access (tx.fhir.org)
34+
- **File Encoding**: UTF-8 (set via JAVA_TOOL_OPTIONS)
35+
36+
### Build Steps
37+
38+
#### 1. Update/Download the IG Publisher (Required First Time)
39+
```bash
40+
./_updatePublisher.sh -y
41+
```
42+
This downloads the latest IG Publisher (~100MB) to `input-cache/publisher.jar`. On Windows, use `_updatePublisher.bat`. The script also updates build scripts from the HL7 repository.
43+
44+
**Important**: This requires internet connectivity to tx.fhir.org. If offline, the build will operate in offline mode with limited terminology validation.
45+
46+
#### 2. Build the Implementation Guide
47+
```bash
48+
./_genonce.sh
49+
```
50+
On Windows, use `_genonce.bat`.
51+
52+
**What this does**:
53+
- Automatically compiles FSH files to FHIR JSON resources
54+
- Validates all resources against FHIR spec and dependencies
55+
- Generates the HTML implementation guide
56+
- Runs terminology validation (if online)
57+
- Outputs to `./output/` directory
58+
59+
**Build Time**: 5-15 minutes depending on system and network speed.
60+
61+
**Memory Configuration**: The build uses `-Xms3550m -Xmx3550m` for Java heap. If you encounter OutOfMemory errors, increase these values in the `_genonce.sh/bat` scripts.
62+
63+
#### 3. Continuous Build (Optional for Development)
64+
```bash
65+
./_gencontinuous.sh
66+
```
67+
This runs the publisher in watch mode, automatically rebuilding when FSH files change.
68+
69+
### Common Build Issues and Solutions
70+
71+
**Issue**: "IG Publisher NOT FOUND"
72+
- **Solution**: Run `./_updatePublisher.sh -y` first
73+
74+
**Issue**: "Offline (or the terminology server is down)"
75+
- **Solution**: This is informational. Build will continue in offline mode with `-tx n/a` option. Terminology validation will be limited.
76+
77+
**Issue**: Java OutOfMemoryError
78+
- **Solution**: Increase Java heap size in `_genonce.sh`: change `-Xms3550m -Xmx3550m` to higher values (e.g., `-Xms4096m -Xmx4096m`)
79+
80+
**Issue**: Build warnings about property definitions in CodeSystem
81+
- **Solution**: These warnings are expected and suppressed in `input/ignoreWarnings.txt`. They relate to NPU terminology properties.
82+
83+
**Issue**: Build warnings about LOINC display names
84+
- **Solution**: Expected - Danish translations for some LOINC codes are not available. These are suppressed in `input/ignoreWarnings.txt`.
85+
86+
### Validation
87+
88+
The IG Publisher automatically validates:
89+
- FSH syntax correctness
90+
- FHIR resource conformance to base FHIR spec
91+
- Profile constraints (invariants, cardinality, bindings)
92+
- Terminology bindings (when online)
93+
- Cross-references between resources
94+
95+
**Known Suppressed Warnings**: See `input/ignoreWarnings.txt` for intentionally suppressed warnings related to:
96+
- Medical device whitespace in examples
97+
- NPU CodeSystem properties
98+
- Missing terminology definitions (NPU, MedCom, SKS codes not available at terminology server)
99+
- LOINC display name translations
100+
101+
### Testing
102+
103+
This repository does not include automated unit tests. Validation occurs through:
104+
1. IG Publisher build validation
105+
2. GitHub Actions CI build (see `.github/workflows/main.yml`)
106+
3. Manual review by HL7 Denmark FHIR SIG
107+
108+
## Project Layout
109+
110+
### Root Directory Files
111+
```
112+
├── README.md # Basic repository information and build instructions
113+
├── sushi-config.yaml # Main IG configuration (metadata, dependencies, menu)
114+
├── ig.ini # IG Publisher configuration (template, IG path)
115+
├── release-notes.md # Version history and changes
116+
├── publication-request.json # Publication metadata for HL7 registry
117+
├── _updatePublisher.sh/.bat # Script to download/update IG Publisher
118+
├── _genonce.sh/.bat # Script to build IG once
119+
├── _gencontinuous.sh/.bat # Script to build IG in watch mode
120+
└── build-notes.txt # Developer notes on publishing process
121+
```
122+
123+
### Input Directory Structure
124+
```
125+
input/
126+
├── fsh/ # FSH source files (all profiles, extensions, terminology)
127+
│ ├── DkCorePatient.fsh # Patient profile
128+
│ ├── DkCoreOrganization.fsh # Organization profile
129+
│ ├── DkCoreObservation.fsh # Observation profiles
130+
│ ├── DkCorePractitioner.fsh # Practitioner profile
131+
│ ├── aliases.fsh # FHIR aliases for common URLs
132+
│ ├── codeSystems.fsh # Danish code systems
133+
│ ├── valueSets.fsh # Danish value sets
134+
│ ├── extensions.fsh # Danish extensions
135+
│ ├── instances.fsh # Example instances and NamingSystems
136+
│ ├── IPAProfiles.fsh # IPA-compliant profiles
137+
│ └── *Identifier.fsh # Various identifier profiles (CPR, SOR, etc.)
138+
├── pagecontent/ # Markdown content for IG pages
139+
│ ├── index.md # IG home page
140+
│ ├── guidance.md # Design guidance
141+
│ ├── downloads.md # Download links page
142+
│ ├── StructureDefinition-*.md # Profile documentation
143+
│ ├── profiles.xml # Profile list page template
144+
│ ├── terminology.xml # Terminology list page template
145+
│ └── extensions.xml # Extension list page template
146+
├── images/ # Images for documentation (currently just placeholder)
147+
└── ignoreWarnings.txt # Validation warnings to suppress
148+
```
149+
150+
### Generated Directories (Gitignored)
151+
```
152+
├── fsh-generated/ # FSH compiler output (FHIR JSON resources)
153+
├── output/ # Final IG HTML and resources
154+
├── input-cache/ # Downloaded IG Publisher and dependencies
155+
├── temp/ # Temporary build files
156+
├── template/ # Downloaded IG template
157+
└── txCache/ # Terminology server cache
158+
```
159+
160+
## GitHub Workflows
161+
162+
### CI Build (`.github/workflows/main.yml`)
163+
Triggers on:
164+
- Push to `main` or `master` branches
165+
- Pull requests to `main` or `master` branches
166+
- Manual workflow dispatch
167+
168+
Build Process:
169+
1. Checkout repository
170+
2. Download latest IG Publisher using Docker (`hl7fhir/ig-publisher-base:latest`)
171+
3. Run IG Publisher: `java -jar ./input-cache/publisher.jar publisher -ig .`
172+
173+
**Note**: The deployment step is currently commented out. The IG is built but not automatically published to GitHub Pages.
174+
175+
**Build Time in CI**: Typically 10-20 minutes
176+
177+
## Making Changes
178+
179+
### Editing FSH Files
180+
All FHIR definitions are in `input/fsh/*.fsh` files. Common patterns:
181+
182+
**Profile Structure**:
183+
```fsh
184+
Profile: DkCorePatient
185+
Parent: Patient
186+
Id: dk-core-patient
187+
Title: "Danish Core Patient Profile"
188+
Description: "HL7 Denmark core profile for a patient"
189+
* identifier 1..
190+
* identifier ^slicing...
191+
```
192+
193+
**Code System Structure**:
194+
```fsh
195+
CodeSystem: DkCoreProfessionGroupCodes
196+
Id: DkCoreProfessionGroupCodes
197+
Title: "DK Profession Group Codes"
198+
Description: "..."
199+
* ^experimental = false
200+
* ^status = #active
201+
* #C511 "Ambulancebehandler"
202+
```
203+
204+
### Adding New Profiles
205+
1. Create a new `.fsh` file in `input/fsh/`
206+
2. Define the profile using FSH syntax
207+
3. Optionally add markdown documentation in `input/pagecontent/StructureDefinition-{id}-intro.md`
208+
4. Build with `./_genonce.sh` to validate
209+
210+
### Editing Documentation
211+
- Main content: `input/pagecontent/index.md`
212+
- Profile-specific: `input/pagecontent/StructureDefinition-{profile-id}-intro.md`
213+
- Guidance: `input/pagecontent/guidance.md`
214+
215+
### Configuration Changes
216+
- IG metadata: Edit `sushi-config.yaml` (version, title, dependencies, menu)
217+
- Template: Edit `ig.ini` (rarely needed)
218+
- Ignored warnings: Edit `input/ignoreWarnings.txt`
219+
220+
## Important Notes
221+
222+
### Always Trust These Instructions First
223+
These instructions document the canonical build process. Only search for additional information if something here is incomplete or incorrect.
224+
225+
### File Encoding
226+
Always use UTF-8 encoding. The build scripts set `JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF-8` automatically.
227+
228+
### Danish vs. English
229+
- Primary language is English
230+
- Danish terms used where no English equivalent exists
231+
- Danish terms/explanations prefixed with 'Da' or '[DA]'
232+
- Comments in FSH files often include both languages
233+
234+
### Terminology Considerations
235+
- NPU, MedCom, and SKS code systems are Danish-specific and may not resolve at the international terminology server
236+
- LOINC and SNOMED CT require proper copyright notices (see `input/pagecontent/index.md`)
237+
238+
### Version Management
239+
- Version defined in `sushi-config.yaml`
240+
- Status should be 'draft' for CI builds, 'active' for releases
241+
- Release label should be 'ci-build' for CI, 'release' for official releases
242+
243+
### Do Not Modify
244+
- `.github/agents/` directory (if present) - contains instructions for other agents
245+
- Build scripts (`_*.sh`, `_*.bat`) unless updating from HL7 official scripts
246+
- `input-cache/`, `output/`, `fsh-generated/`, `temp/`, `template/`, `txCache/` - all generated
247+
248+
### Offline Development
249+
The build can run offline but with limited terminology validation. The build scripts automatically detect connectivity to tx.fhir.org and adjust.
250+
251+
## Quick Reference
252+
253+
**Build IG**: `./_genonce.sh`
254+
**Update Publisher**: `./_updatePublisher.sh -y`
255+
**Watch Mode**: `./_gencontinuous.sh`
256+
**View Output**: Open `output/index.html` in browser after build
257+
**Check Validation**: Review `output/qa.html` for validation issues

0 commit comments

Comments
 (0)