From 029340b0e0d15c401a8024d48e58ad45f5a1e599 Mon Sep 17 00:00:00 2001 From: dotasek Date: Wed, 5 Jan 2022 15:42:49 -0500 Subject: [PATCH 1/4] Merge readme.md into CONVERTORS.md --- org.hl7.fhir.convertors/CONVERTORS.md | 36 ++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/org.hl7.fhir.convertors/CONVERTORS.md b/org.hl7.fhir.convertors/CONVERTORS.md index fac030a52..ca3e1cdef 100644 --- a/org.hl7.fhir.convertors/CONVERTORS.md +++ b/org.hl7.fhir.convertors/CONVERTORS.md @@ -1,6 +1,14 @@ # Resource Conversion -##### Let's talk about converting resources between the various versions of FHIR... +##IMPORTANT + +_The conversion code in this module is maintained as part of the development of the standard, but always under +considerable time pressure. Only part of the code is rigorously tested [as detailed here](#reliable-conversion-code) +Implementers should regard this code as a 'scaffold' for actual reliable conversions._ + +**Always test any conversion routines before using them in production** + +_Ideally, this should be via unit tests in your code, or better yet [unit tests in this module](#test-cases)._ ### A note regarding syntax @@ -193,3 +201,29 @@ Once you've created your new advisor, they can be provided as an argument when c `public static (V1 Resource) convertResource((V2 Resource) src, advisor)` `public static (V2 Resource) convertResource((V1 Resource) src, advisor)` + +## Development notes + +### Reliable conversion code + +The FHIR project maintains and tests conversions on the following resources, from old versions to R5: + +- CodeSystem +- ValueSet +- ConceptMap +- StructureDefinition +- StructureMap +- ImplementationGuide +- CapabilityStatement +- OperationDefinition +- NamingSystem + +These can be relied on and are subject to extensive testing. + +### Test cases + +Some conversions have test cases for particular resources and particular version combinations. Where test cases exist, +they will continue to be maintained and expected to pass. + +Contributing test cases is encouraged! To contribute, create a PRs to the core library, or even better, to the FHIR +test cases library. From 45a2516fd8eb472a5607d81fcca229784c39cee4 Mon Sep 17 00:00:00 2001 From: dotasek Date: Wed, 5 Jan 2022 15:43:36 -0500 Subject: [PATCH 2/4] Replace readme.md with CONVERTORS.md --- .../{CONVERTORS.md => README.md} | 0 org.hl7.fhir.convertors/readme.md | 32 ------------------- 2 files changed, 32 deletions(-) rename org.hl7.fhir.convertors/{CONVERTORS.md => README.md} (100%) delete mode 100644 org.hl7.fhir.convertors/readme.md diff --git a/org.hl7.fhir.convertors/CONVERTORS.md b/org.hl7.fhir.convertors/README.md similarity index 100% rename from org.hl7.fhir.convertors/CONVERTORS.md rename to org.hl7.fhir.convertors/README.md diff --git a/org.hl7.fhir.convertors/readme.md b/org.hl7.fhir.convertors/readme.md deleted file mode 100644 index c9faf8154..000000000 --- a/org.hl7.fhir.convertors/readme.md +++ /dev/null @@ -1,32 +0,0 @@ -About the version conversion routines - -The version conversion routines are maintained as part of -the development of the standard, but always under considerable -time pressure. Implementers should regard these as 'scaffolds' for -an actual reliable conversion routine. - -The FHIR project maintains and tests conversions on the following -resources, from old versions to R5: -* CodeSystem -* ValueSet -* ConceptMap -* StructureDefinition -* StructureMap -* ImplementationGuide -* CapabilityStatement -* OperationDefinition -* NamingSystem - -These can be relied on and are subject to extensive testing. - -In addition to this, some of the conversions have test cases -for particular resources and particular version combinations. -Where test cases exist, they will continue to pass and be -maintained. - -So: -* test the conversion routines before using them in production -* contribute test cases to ensure that your use cases continue to be reliable - -Test cases are welcome - make them as PRs to the core library, or even better, -to the FHIR test cases library \ No newline at end of file From 0edcf819ea7300fc600565cd658e03ebf76afc80 Mon Sep 17 00:00:00 2001 From: dotasek Date: Wed, 5 Jan 2022 15:45:27 -0500 Subject: [PATCH 3/4] Fix format --- org.hl7.fhir.convertors/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/org.hl7.fhir.convertors/README.md b/org.hl7.fhir.convertors/README.md index ca3e1cdef..891cf35d2 100644 --- a/org.hl7.fhir.convertors/README.md +++ b/org.hl7.fhir.convertors/README.md @@ -1,6 +1,6 @@ # Resource Conversion -##IMPORTANT +## IMPORTANT _The conversion code in this module is maintained as part of the development of the standard, but always under considerable time pressure. Only part of the code is rigorously tested [as detailed here](#reliable-conversion-code) From 189a7ebdfbbb9cb50cd0163bc9e57e7985c5ba53 Mon Sep 17 00:00:00 2001 From: dotasek Date: Wed, 5 Jan 2022 15:54:06 -0500 Subject: [PATCH 4/4] Update README.md Formatting improvements. Additional links. --- org.hl7.fhir.convertors/README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/org.hl7.fhir.convertors/README.md b/org.hl7.fhir.convertors/README.md index 891cf35d2..ea5333005 100644 --- a/org.hl7.fhir.convertors/README.md +++ b/org.hl7.fhir.convertors/README.md @@ -1,14 +1,15 @@ # Resource Conversion ## IMPORTANT +----- _The conversion code in this module is maintained as part of the development of the standard, but always under -considerable time pressure. Only part of the code is rigorously tested [as detailed here](#reliable-conversion-code) +considerable time pressure. Only part of the code is rigorously tested [as detailed here](#reliable-conversion-code). Implementers should regard this code as a 'scaffold' for actual reliable conversions._ -**Always test any conversion routines before using them in production** +**ALWAYS TEST ANY CONVERSION ROUTINES BEFORE USING THEM IN PRODUCTION!** -_Ideally, this should be via unit tests in your code, or better yet [unit tests in this module](#test-cases)._ +_Ideally, this should be via unit tests in your code, or better yet [unit tests contributed to FHIR](#test-cases)._ ### A note regarding syntax @@ -39,7 +40,7 @@ and [r4](http://hl7.org/fhir/R4/account.html) **N.B.** This information is only for code navigation purposes. It is important that when converting between versions you use the provided conversion factory classes as your entry point. -### Using the conversion library +## Using the conversion library ----- The majority of use cases for conversion will involve using the provided VersionConvertorFactory_V1_V2 classes to convert @@ -203,6 +204,7 @@ Once you've created your new advisor, they can be provided as an argument when c `public static (V2 Resource) convertResource((V1 Resource) src, advisor)` ## Development notes +----- ### Reliable conversion code @@ -225,5 +227,6 @@ These can be relied on and are subject to extensive testing. Some conversions have test cases for particular resources and particular version combinations. Where test cases exist, they will continue to be maintained and expected to pass. -Contributing test cases is encouraged! To contribute, create a PRs to the core library, or even better, to the FHIR -test cases library. +Contributing test cases is highly encouraged! To contribute, create a PRs to the +[core library](https://github.com/hapifhir/org.hl7.fhir.core), or even better, to the +[FHIR test cases library](https://github.com/FHIR/fhir-test-cases).