Interacting with the PH Core IG in an agile fashion - UP-Manila-SILab/ph-core GitHub Wiki

Developers can leverage the dev and current settings within the Sushi and IG Publisher toolchain to streamline interactions with the ph-core IG, especially when developing dependent IGs like NHDR and Immunisation, and when performing refactoring for redundancy removal. This article will provide an instructive guide on how to utilize these powerful features for agile inter-project development.

Interacting with ph-core IG using dev and current settings

The Sushi and IG Publisher toolchain offers flexible dependency resolution, allowing developers to reference both locally built IGs and those hosted on build.fhir.org. This capability significantly accelerates development workflows for interrelated IGs.

Understanding dev and current

The fshschool.org documentation (specifically, https://fshschool.org/docs/sushi/configuration/#dependencies) details the dev and current special version identifiers. Here's a breakdown of their practical applications:

  • current mode: This mode allows you to depend on the latest successful build of an IG on build.fhir.org. This is ideal for agile development where you want to build your IG against the most up-to-date, albeit potentially temporary, version of a dependency.
  • dev mode: This mode enables you to depend on a locally built version of an IG. This is particularly powerful for refactoring and making consistent changes across multiple IGs, as it allows you to test your changes against a dependency that is also under active local development.

Practical Applications

1. Building Multiple IGs in Agile Fashion Against Temporary Builds (current mode)

This scenario is common when IGs like NHDR and Immunisation rely on ph-core. Instead of waiting for a formal release of ph-core, you can develop against its current build on build.fhir.org.

How to implement current mode:

  1. Ensure ph-core is building on build.fhir.org: For this to work, the ph-core IG must be configured to build and publish its current version to build.fhir.org.

  2. Configure your dependent IG's sushi-config.yaml: In the sushi-config.yaml file of your dependent IG (e.g., NHDR or Immunisation), you'll specify the ph-core dependency with the current version identifier.

    # sushi-config.yaml for NHDR or Immunisation IG
id: your.ig.id
name: YourIG
status: active
dependencies:
  example.fhir.ph.core: # This is the package ID of ph-core
    version: current # Use 'current' to depend on the latest build

  3. Run Sushi and IG Publisher: When you run Sushi and the IG Publisher for your dependent IG, the toolchain will fetch the current build of ph-core from build.fhir.org and resolve dependencies against it.

    sushi .
# followed by IG Publisher commands

Benefits:

  • Faster Iteration: You can develop and test your IG against the most recent changes in ph-core without waiting for formal releases.
  • Early Issue Detection: Identify compatibility issues with ph-core earlier in the development cycle.

2. Refactoring Multiple IGs in Agile Fashion Against Local Builds (dev mode)

This mode is invaluable for scenarios like removing duplication between NHDR and ph-core, where you need to make coordinated changes across both IGs. It allows you to move elements between the IGs and immediately test the impact.

How to implement dev mode:

  1. Clone both IGs locally: Ensure you have local copies of both the ph-core IG and the dependent IG (e.g., NHDR) on your development machine.

  2. Build ph-core locally: First, navigate to your local ph-core directory and build it using Sushi. This will generate a local package that your dependent IG can reference.

    cd /path/to/your/local/ph-core-ig
sushi .

  3. Configure your dependent IG's sushi-config.yaml: In the sushi-config.yaml of your dependent IG, you'll specify the ph-core dependency with the dev version identifier.

    # sushi-config.yaml for NHDR IG
id: your.ig.id
name: YourIG
status: active
dependencies:
  example.fhir.ph.core: # This is the package ID of ph-core
    version: dev # Use 'dev' to depend on your local build

  4. Run Sushi and IG Publisher for the dependent IG: Now, when you run Sushi and the IG Publisher for your dependent IG, it will look for and utilize your locally built ph-core package.

    cd /path/to/your/local/nhdr-ig
sushi .
# followed by IG Publisher commands

  5. Iterative Refactoring: You can now make changes in ph-core (e.g., moving an element) and immediately update NHDR to reflect those changes. After each change, rebuild ph-core locally (sushi in ph-core directory) and then rebuild NHDR (sushi in NHDR directory) to test the impact.

Benefits:

  • Seamless Refactoring: Perform complex refactoring operations across multiple IGs with immediate feedback.
  • Eliminate Duplication: Efficiently identify and remove redundant elements by moving them to the appropriate core IG.
  • Consistent Changes: Ensure changes are applied consistently across all dependent IGs.

Conclusion

The dev and current settings within the Sushi and IG Publisher toolchain provide developers with powerful mechanisms for agile inter-project development. By embracing these features, IG teams can significantly accelerate their work, improve consistency, and streamline the refactoring process, ultimately leading to higher quality and more maintainable FHIR Implementation Guides. While these are technical vehicles, open communication and collaboration between IG teams remain crucial to fully leverage the benefits of faster progress.