-
Notifications
You must be signed in to change notification settings - Fork 0
bonfhir/bonfhir.github.io
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
<!doctype html> <html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-contributing" data-has-hydrated="false"> <head> <meta charset="UTF-8"> <meta name="generator" content="Docusaurus v3.2.1"> <title data-rh="true">Contributing to bonFHIR | bonFHIR</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://bonfhir.dev/img/bonfhir-card.png"><meta data-rh="true" name="twitter:image" content="https://bonfhir.dev/img/bonfhir-card.png"><meta data-rh="true" property="og:url" content="https://bonfhir.dev/docs/contributing"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Contributing to bonFHIR | bonFHIR"><meta data-rh="true" name="description" content="bonFHIR is an open-source project and we welcome contributors."><meta data-rh="true" property="og:description" content="bonFHIR is an open-source project and we welcome contributors."><link data-rh="true" rel="icon" href="/img/favicon.ico"><link data-rh="true" rel="canonical" href="https://bonfhir.dev/docs/contributing"><link data-rh="true" rel="alternate" href="https://bonfhir.dev/docs/contributing" hreflang="en"><link data-rh="true" rel="alternate" href="https://bonfhir.dev/docs/contributing" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://C444QI5SK7-dsn.algolia.net" crossorigin="anonymous"><link rel="preconnect" href="https://www.google-analytics.com"> <link rel="preconnect" href="https://www.googletagmanager.com"> <script async src="https://www.googletagmanager.com/gtag/js?id=G-R0EMRLV0G9"></script> <script>function gtag(){dataLayer.push(arguments)}window.dataLayer=window.dataLayer||[],gtag("js",new Date),gtag("config","G-R0EMRLV0G9",{})</script> <link rel="search" type="application/opensearchdescription+xml" title="bonFHIR" href="/opensearch.xml"><link rel="stylesheet" href="/assets/css/styles.91c5cfb2.css"> <script src="/assets/js/runtime~main.09e864ec.js" defer="defer"></script> <script src="/assets/js/main.457acc4c.js" defer="defer"></script> </head> <body class="navigation-with-keyboard"> <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return localStorage.getItem("theme")}catch(t){}}();t(null!==e?e:"light")}(),function(){try{const a=new URLSearchParams(window.location.search).entries();for(var[t,e]of a)if(t.startsWith("docusaurus-data-")){var n=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(n,e)}}catch(t){}}(),document.documentElement.setAttribute("data-announcement-bar-initially-dismissed",function(){try{return"true"===localStorage.getItem("docusaurus.announcement.dismiss")}catch(t){}return!1}())</script><div id="__docusaurus"><div role="region" aria-label="Skip to main content"><a class="skipToContent_ins6" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><div class="announcementBar_QYgG" style="background-color:#fafbfc;color:#091E42" role="banner"><div class="announcementBarPlaceholder_AI0J"></div><div class="content_brLI announcementBarContent_DYWN">We are launching a new service to help you with your FHIR data modeling. <a target="_blank" rel="noopener noreferrer" href="https://calendly.com/acn-fhir">Book a consultation</a> with us!</div><button type="button" aria-label="Close" class="clean-btn close closeButton_PYWl announcementBarClose_U5yF"><svg viewBox="0 0 15 15" width="14" height="14"><g stroke="currentColor" stroke-width="3.1"><path d="M.75.75l13.5 13.5M14.25.75L.75 14.25"></path></g></svg></button></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/bonfhir_logo.svg" alt="bonFHIR" class="themedComponent__ygk themedComponent--light_ORKY"><img src="/img/bonfhir_logo.svg" alt="bonFHIR" class="themedComponent__ygk themedComponent--dark_sACM"></div></a></div><div class="navbar__items navbar__items--right"><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/welcome">Get Started</a><a class="navbar__item navbar__link" href="/packages/intro">Packages Documentation</a><a href="https://bonfhir.dev/storybook" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Storybook<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_dVMP"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><a href="https://github.com/bonfhir/bonfhir" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_dVMP"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><div class="searchBox navbarSearchContainer_KfFV"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_TBnd"><div class="docsWrapper_BuON"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_LEGs" type="button"></button><div class="docRoot_OFFb"><aside class="theme-doc-sidebar-container docSidebarContainer_H40T"><div class="sidebarViewport_dh84"><div class="sidebar_CdHk"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_IVrm menuWithAnnouncementBar_FbPa"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/welcome">Welcome to Bonfhir</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/build-a-fhir-app-with-react">Build a FHIR app with React</a><button aria-label="Expand sidebar category 'Build a FHIR app with React'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/build-a-subscription-api-with-aws-lambda">Build a Subscription API with AWS Lambda</a><button aria-label="Expand sidebar category 'Build a Subscription API with AWS Lambda'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/build-a-fhir-solution-with-nextjs">Build a FHIR solution with Next.js</a><button aria-label="Expand sidebar category 'Build a FHIR solution with Next.js'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/build-workflows-with-n8n">Build Workflows with n8n</a><button aria-label="Expand sidebar category 'Build Workflows with n8n'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/guides">Guides</a><button aria-label="Expand sidebar category 'Guides'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" href="/docs/contributing">Contributing to bonFHIR</a></li></ul></nav></div></div></aside><main class="docMainContainer_XBsP"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_mvgL"><div class="docItemContainer_UeFT"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_bNjk" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_H2RH"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Contributing to bonFHIR</span><meta itemprop="position" content="1"></li></ul></nav><div class="tocCollapsible_q4FV theme-doc-toc-mobile tocMobile_HWYQ"><button type="button" class="clean-btn tocCollapsibleButton_oR_R">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Contributing to bonFHIR</h1></header><p>bonFHIR is an open-source project and we welcome contributors.<br> <!-- -->Here are a few guidelines.</p> <h2 class="anchor anchorWithStickyNavbar_i8YX" id="ways-to-contribute">Ways to contribute<a href="#ways-to-contribute" class="hash-link" aria-label="Direct link to Ways to contribute" title="Direct link to Ways to contribute"></a></h2> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="found-a-bug">Found a bug?<a href="#found-a-bug" class="hash-link" aria-label="Direct link to Found a bug?" title="Direct link to Found a bug?"></a></h3> <ul> <li> <p><strong>Ensure the bug was not already reported</strong> by searching on GitHub under <a href="https://github.com/bonfhir/bonfhir/issues" target="_blank" rel="noopener noreferrer">Issues</a>.</p> </li> <li> <p>If you're unable to find an open issue addressing the problem, <a href="https://github.com/bonfhir/bonfhir/issues/new" target="_blank" rel="noopener noreferrer">open a new one</a>. Be sure to include a <strong>title and clear description</strong>, as much relevant information as possible, and a <strong>code sample</strong> or an <strong>executable test case</strong> demonstrating the expected behavior that is not occurring.</p> </li> </ul> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="fix-a-bug-or-improve-the-documentation">Fix a bug or improve the documentation?<a href="#fix-a-bug-or-improve-the-documentation" class="hash-link" aria-label="Direct link to Fix a bug or improve the documentation?" title="Direct link to Fix a bug or improve the documentation?"></a></h3> <ul> <li>Open a new GitHub pull request with the patch.</li> <li>Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.</li> <li>Don't forget to include the appropriate changeset description (see below for more details)</li> <li>Please monitor the CI build result and fix any problems. A good way to do it is to first open a <strong>Draft</strong> PR so that the build can run, prior to mark it ready for review</li> <li>Once your PR is merged, your contributions will be publicly visible on the packages CHANGELOG.</li> </ul> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="add-a-new-feature-or-change-an-existing-one">Add a new feature or change an existing one?<a href="#add-a-new-feature-or-change-an-existing-one" class="hash-link" aria-label="Direct link to Add a new feature or change an existing one?" title="Direct link to Add a new feature or change an existing one?"></a></h3> <ul> <li>If the change is small enough, you can try your luck with opening a PR - see the <a href="#fix-a-bug-or-improve-the-documentation">patch instructions</a> above.</li> <li>Otherwise, please <a href="https://github.com/bonfhir/bonfhir/discussions" target="_blank" rel="noopener noreferrer">create a new discussion</a>, explains your intended changes, and be prepared to be asked for code snippets or POCs 🙂</li> </ul> <h2 class="anchor anchorWithStickyNavbar_i8YX" id="get-started---running-the-bonfhir-solution">Get started - running the bonFHIR solution<a href="#get-started---running-the-bonfhir-solution" class="hash-link" aria-label="Direct link to Get started - running the bonFHIR solution" title="Direct link to Get started - running the bonFHIR solution"></a></h2> <p>bonFHIR is a monorepo that contains all the bonFHIR packages, websites and documentation.<br> <!-- -->The monorepo uses <a href="https://pnpm.io" target="_blank" rel="noopener noreferrer"><code>pnpm</code></a> as a package manager, and <a href="https://turbo.build/repo" target="_blank" rel="noopener noreferrer"><code>turborepo</code></a> as the build system.</p> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="pre-requisites">Pre-requisites<a href="#pre-requisites" class="hash-link" aria-label="Direct link to Pre-requisites" title="Direct link to Pre-requisites"></a></h3> <ul> <li><a href="https://nodejs.org/en/download" target="_blank" rel="noopener noreferrer">Node LTS</a></li> <li><a href="https://pnpm.io/installation" target="_blank" rel="noopener noreferrer">pnpm</a></li> <li><a href="https://docs.docker.com/desktop/" target="_blank" rel="noopener noreferrer">Docker</a></li> <li>Visual Studio Code - optional, but recommended - there are recommended extensions on the repo that you might want to install as well</li> </ul> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="build-run-the-checks-and-run-the-tests">Build, run the checks, and run the tests<a href="#build-run-the-checks-and-run-the-tests" class="hash-link" aria-label="Direct link to Build, run the checks, and run the tests" title="Direct link to Build, run the checks, and run the tests"></a></h3> <ul> <li>Clone the repository</li> <li><code>pnpm install</code></li> <li><code>pnpm build</code> - run the build for all packages</li> <li><code>pnpm check</code> - run the quality checks for all packages (prettier, eslint, and type checking)</li> <li><code>pnpm test</code> - run the unit tests for all packages</li> <li><code>pnpm all</code> - run <code>build</code>, <code>check</code> and <code>test</code></li> </ul> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="run-the-sample-apps">Run the sample apps<a href="#run-the-sample-apps" class="hash-link" aria-label="Direct link to Run the sample apps" title="Direct link to Run the sample apps"></a></h3> <p>Samples apps are in the <code>apps</code> directory.</p> <ol> <li> <p>Build all the packages in the monorepo</p> </li> <li> <p>Start the local FHIR Server:</p> </li> </ol> <ul> <li><code>pnpm fhir:start-server</code> <ul> <li>after a bit of time, this starts a local <a href="https://medplum.com" target="_blank" rel="noopener noreferrer">MedPlum Instance</a> accessible at <a href="http://localhost:8100" target="_blank" rel="noopener noreferrer">http://localhost:8100</a> <ul> <li>login with <a href="mailto:[email protected]" target="_blank" rel="noopener noreferrer">[email protected]</a> / medplum_admin</li> <li>select the "Default" project</li> </ul> </li> </ul> </li> <li><code>pnpm fhir:add-sample-data</code> - this kicks-off a sample data import (synthetic patients) into the local FHIR server so that you have valid FHIR data to work with</li> </ul> <ol start="3"> <li>Run the apps using <code>pnpm dev</code> in their respective directory.</li> </ol> <h2 class="anchor anchorWithStickyNavbar_i8YX" id="develop-in-bonfhir">Develop in bonFHIR<a href="#develop-in-bonfhir" class="hash-link" aria-label="Direct link to Develop in bonFHIR" title="Direct link to Develop in bonFHIR"></a></h2> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="where-to-write-new-code">Where to write new code?<a href="#where-to-write-new-code" class="hash-link" aria-label="Direct link to Where to write new code?" title="Direct link to Where to write new code?"></a></h3> <p>bonFHIR is meant to be compatible with multiple FHIR versions at the same time (currently R4B and R5). The way this works for <em>most</em> packages is:</p> <ul> <li>you should write your code and tests in the <code>src/r5</code> directory<!-- --> <ul> <li>to run the tests without having to rebuild all the time, you can simply scope your test runner using <code>pnpm run test src/r5 --watch</code></li> </ul> </li> <li>when running the <code>pnpm build</code> component for the package, all files from <code>src/r5</code> are copied to <code>src/r4b</code>, and the FHIR path is substituted to the appropriate version prior to the package being bundled</li> </ul> <blockquote> <p>Code written in `r4b`` is squashed during the build, so you <strong>will loose</strong> it when the build commands run.</p> </blockquote> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="code-generator">Code generator<a href="#code-generator" class="hash-link" aria-label="Direct link to Code generator" title="Direct link to Code generator"></a></h3> <p>Some projects includes code generation sourced from the official FHIR definition files.<br> <!-- -->In that case, the <code>@bonfhir/codegen</code> is used to run the files in the <code>templates</code> directory and produce artifacts in the <code>src/r4b</code> and <code>src/r5</code> directories.</p> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="bundling-and-cross-project-references">Bundling and cross-project references<a href="#bundling-and-cross-project-references" class="hash-link" aria-label="Direct link to Bundling and cross-project references" title="Direct link to Bundling and cross-project references"></a></h3> <p>The <code>pnpm build</code> command runs the template generation, copy files over from <code>src/r5</code>, and then launches <a href="https://rollupjs.org/" target="_blank" rel="noopener noreferrer">rollup</a> to bundle the code into the different versions (R4B, R5, CJS, ESM...) into the <code>dist/</code> directory.<br> <!-- -->bonFHIR dependencies are excluded from the bundling - some dev dependencies may get bundled in.</p> <p>Local package references work by using pnpm workspace references to the <code>package.json</code> file, that itself references the <code>dist</code> directory.<br> <!-- -->What that means is that the code from one package uses the <em>bundled</em> version of the code from its dependencies, not the source code directly. Most of the packages include a <code>pnpm dev</code> script that should automatically re-build the package when a file change so it is easier to support cross-package development.</p> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="changesets---versioning-packages">Changesets - versioning packages<a href="#changesets---versioning-packages" class="hash-link" aria-label="Direct link to Changesets - versioning packages" title="Direct link to Changesets - versioning packages"></a></h3> <p>You should <strong>never</strong> change a package version manually. The monorepo uses <a href="https://github.com/changesets/changesets" target="_blank" rel="noopener noreferrer">changesets</a> to manage the release and versioning process.</p> <p>When commiting your changes, please ensure that you have a <em>clean commit history</em>, and that each individual commit contains:</p> <ul> <li>a unit of change (that will appear as a item in the changelog of each package)</li> <li>a changeset file containing a description of those changes, along with the versionning information</li> </ul> <p>To generate a changeset file, simpy run the <code>pnpm changeset</code> command at the root of the repo.<br> <!-- -->This generates a new file in the <code>.changeset</code> folder. Make sure to commit this file along with the changes so they are associated.</p> <p>A PR can contain multiple such commits. Be mindful of the PR sizes though, as larger PR tend to be vry hard to review.<br> <!-- -->You may get ask to break it down, and clean-up your git history.</p> <p>After the PR is merged, a new PR is generated - entitled "Version Package", that will in turn version and publish new packages once it is merged. That's how bonFHIR is released. As a contributor, you should <strong>not</strong> merge the "Version Package" PR.</p> <blockquote> <p>To get a PR to build properly without a package version changed (for exemple a change to the website or documentation) use the <code>pnpm changeset --empty</code> command to generate an empty changeset.</p> </blockquote> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="a-good-commit">A good commit<a href="#a-good-commit" class="hash-link" aria-label="Direct link to A good commit" title="Direct link to A good commit"></a></h3> <p>See for example <a href="https://github.com/bonfhir/bonfhir/commit/acda6629c0af50ce5824501a9f01b1dc595e0dda" target="_blank" rel="noopener noreferrer">https://github.com/bonfhir/bonfhir/commit/acda6629c0af50ce5824501a9f01b1dc595e0dda</a>.<br> <!-- -->A good commit should:</p> <ul> <li>contains all the changes related to the linked issue, but no more</li> <li>include all FHIR version changes at the same time (e.g. <code>src/r4b</code> and <code>src/r5</code>)</li> <li>update relevant unit-tests pertinent to the changes, and make sure code is covered appropriately</li> <li>passes all <code>pnpm check</code> and <code>pnpm test</code> scripts - so it conforms with the prettier, eslint and type check requirements</li> <li>contains the relevant documentation update</li> <li>update the storybook stories if they are impacted</li> <li>has a valid changeset with an appropriate description and link to the source issue</li> </ul> <blockquote> <p>A good practice prior to commit is to run the <code>pnpm all</code> command at the root of the monorepo. This builds, checks and tests all packages to ensure that everything is good prior to the CI run.</p> </blockquote> <h2 class="anchor anchorWithStickyNavbar_i8YX" id="maintain-version-consistency-across-package-dependencies">Maintain version consistency across package dependencies<a href="#maintain-version-consistency-across-package-dependencies" class="hash-link" aria-label="Direct link to Maintain version consistency across package dependencies" title="Direct link to Maintain version consistency across package dependencies"></a></h2> <p>bonFHIR is maintained as a monorepo using <a href="https://turbo.build/" target="_blank" rel="noopener noreferrer">turbo</a> and <a href="https://pnpm.io/" target="_blank" rel="noopener noreferrer">pnpm</a>.</p> <p>Some packages have common dependencies. As a good practice, we want to ensure that all dependencies in the monorepo have the same version - what that means is that if <code>@bonfhir/react</code> and <code>@bonfhir/mantine</code> both have a dependency on the <code>react</code> package, we want to make sure that version is the same; maintain version consistency across package depndencies.</p> <p>There are 2 moments in the maintenance of the packages where this is important:</p> <ul> <li>when adding new dependencies</li> <li>when updating dependencies</li> </ul> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="adding-dependencies">Adding dependencies<a href="#adding-dependencies" class="hash-link" aria-label="Direct link to Adding dependencies" title="Direct link to Adding dependencies"></a></h3> <p><em>This is true as well when creating new packages.</em> When adding new dependencies to a package, we want to make sure to use the same version of the package if another bonFHIR package already uses the same dependency.</p> <p>In order to achieve this:</p> <ol> <li> <p>always check in the monorepo if another package already uses that same dependency, by using the <code>pnpm packages:lookup</code> command</p> <div class="language-bash codeBlockContainer_eWpx theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_EltD"><pre tabindex="0" class="prism-code language-bash codeBlock_Klck thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_d3eb"><span class="token-line" style="color:#F8F8F2"><span class="token plain">pnpm packages:lookup left-pad</span><br></span></code></pre><div class="buttonGroup_FYM5"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_rGTz" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_NVkj"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_h7xD"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> </li> <li> <p>If the previous command returns nothing, then simply add the dependency as usual.</p> </li> <li> <p>If it does, please lookupthe version specifier in the <code>package.json</code> file where it is present, and use the same when adding it</p> </li> </ol> <div class="theme-admonition theme-admonition-info admonition_f1ls alert alert--info"><div class="admonitionHeading_avEv"><span class="admonitionIcon_ZkFx"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Walkthrough</div><div class="admonitionContent_TH3Y"><p>Let's imagine that we need to add the <code>remarkable</code> package as a dependency of <code>@bonfhir/react</code>.</p><ol> <li>Lookup existing information</li> </ol><div class="language-bash codeBlockContainer_eWpx theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_EltD"><pre tabindex="0" class="prism-code language-bash codeBlock_Klck thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_d3eb"><span class="token-line" style="color:#F8F8F2"><span class="token plain">pnpm packages:lookup remarkable</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">> bonfhir@ packages:lookup bonfhir/bonfhir</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">> pnpm why -r "remarkable"</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Legend: production dependency, optional only, dev only</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">@bonfhir/[email protected] bonfhir/bonfhir/packages/core</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">devDependencies:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">remarkable 2.0.1</span><br></span></code></pre><div class="buttonGroup_FYM5"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_rGTz" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_NVkj"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_h7xD"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><ol start="2"> <li>Found it! It is used by the <code>@bonfhir/core</code> package. Let's look at the <code>package.json</code> file:</li> </ol><div class="language-json codeBlockContainer_eWpx theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_EltD"><pre tabindex="0" class="prism-code language-json codeBlock_Klck thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_d3eb"><span class="token-line" style="color:#F8F8F2"><span class="token plain">{</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> "name": "@bonfhir/core",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> "version": "2.19.2",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> "description": "Core FHIR resources and utilities for BonFHIR",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> //...</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> "devDependencies": {</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> //...</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> "remarkable": "^2.0.1"</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> //...</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> //...</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">}</span><br></span></code></pre><div class="buttonGroup_FYM5"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_rGTz" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_NVkj"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_h7xD"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><ol start="3"> <li>Install with the same version moniker:</li> </ol><div class="language-bash codeBlockContainer_eWpx theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_EltD"><pre tabindex="0" class="prism-code language-bash codeBlock_Klck thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_d3eb"><span class="token-line" style="color:#F8F8F2"><span class="token plain">pnpm add remarkable@^2.0.1</span><br></span></code></pre><div class="buttonGroup_FYM5"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_rGTz" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_NVkj"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_h7xD"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div> <h3 class="anchor anchorWithStickyNavbar_i8YX" id="updating-dependencies">Updating dependencies<a href="#updating-dependencies" class="hash-link" aria-label="Direct link to Updating dependencies" title="Direct link to Updating dependencies"></a></h3> <p>Always update dependencies from the root of the monorepo, to ensure that all packages are updated equally.</p> <p>To identify outdated dependencies, first run:</p> <div class="language-bash codeBlockContainer_eWpx theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_EltD"><pre tabindex="0" class="prism-code language-bash codeBlock_Klck thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_d3eb"><span class="token-line" style="color:#F8F8F2"><span class="token plain">pnpm packages:outdated</span><br></span></code></pre><div class="buttonGroup_FYM5"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_rGTz" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_NVkj"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_h7xD"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <p>This creates a file named <code>outdated.log</code> that can be opened in your editor - e.g. <code>code outdated.log</code>. This file lists all the dependencies across the monorepo that have an update available, with the projects that use them.</p> <p>Identify the packages you want to update, and then run the <code>pnpm packages:update</code> command:</p> <div class="language-bash codeBlockContainer_eWpx theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_EltD"><pre tabindex="0" class="prism-code language-bash codeBlock_Klck thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_d3eb"><span class="token-line" style="color:#F8F8F2"><span class="token plain">pnpm packages:update turbo rollup '@mantine/*' '@tabler/*'</span><br></span></code></pre><div class="buttonGroup_FYM5"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_rGTz" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_NVkj"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_h7xD"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <blockquote> <p>Notice how multiple packages can be specified, whether different names or with the same npm organization.</p> </blockquote> <p>This process ensure that all projects are updated with the same version, and that the monorepo stay consistent.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col"><a href="https://github.com/bonfhir/bonfhir/tree/main/docs/website/docs/contributing.md" target="_blank" rel="noopener noreferrer" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_vDo9" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_ti71"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/guides/ig-toolbox"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Create a FHIR Implementation Guide with IG Toolbox</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_ARYS thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#ways-to-contribute" class="table-of-contents__link toc-highlight">Ways to contribute</a><ul><li><a href="#found-a-bug" class="table-of-contents__link toc-highlight">Found a bug?</a></li><li><a href="#fix-a-bug-or-improve-the-documentation" class="table-of-contents__link toc-highlight">Fix a bug or improve the documentation?</a></li><li><a href="#add-a-new-feature-or-change-an-existing-one" class="table-of-contents__link toc-highlight">Add a new feature or change an existing one?</a></li></ul></li><li><a href="#get-started---running-the-bonfhir-solution" class="table-of-contents__link toc-highlight">Get started - running the bonFHIR solution</a><ul><li><a href="#pre-requisites" class="table-of-contents__link toc-highlight">Pre-requisites</a></li><li><a href="#build-run-the-checks-and-run-the-tests" class="table-of-contents__link toc-highlight">Build, run the checks, and run the tests</a></li><li><a href="#run-the-sample-apps" class="table-of-contents__link toc-highlight">Run the sample apps</a></li></ul></li><li><a href="#develop-in-bonfhir" class="table-of-contents__link toc-highlight">Develop in bonFHIR</a><ul><li><a href="#where-to-write-new-code" class="table-of-contents__link toc-highlight">Where to write new code?</a></li><li><a href="#code-generator" class="table-of-contents__link toc-highlight">Code generator</a></li><li><a href="#bundling-and-cross-project-references" class="table-of-contents__link toc-highlight">Bundling and cross-project references</a></li><li><a href="#changesets---versioning-packages" class="table-of-contents__link toc-highlight">Changesets - versioning packages</a></li><li><a href="#a-good-commit" class="table-of-contents__link toc-highlight">A good commit</a></li></ul></li><li><a href="#maintain-version-consistency-across-package-dependencies" class="table-of-contents__link toc-highlight">Maintain version consistency across package dependencies</a><ul><li><a href="#adding-dependencies" class="table-of-contents__link toc-highlight">Adding dependencies</a></li><li><a href="#updating-dependencies" class="table-of-contents__link toc-highlight">Updating dependencies</a></li></ul></li></ul></div></div></div></div></main></div></div></div></div> </body> </html>
![https://bonfhir.dev/img/bonfhir-card.png"><meta](https://bonfhir.dev/img/bonfhir-card.png"><meta){kind=link}
About
No description, website, or topics provided.
Contributing
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published