2e:null 2f:["$","title",null,{"children":"Version locking for notebook imports | Observable | Observable"}] 34:T88b3,

Indirect imports are notebooks imported by notebooks that you imported directly.

35:T436,## Locking and Unlocking Imports - To lock or unlock imports individually: - Clicking the lock symbol will toggle the lock state to "unlocked", causing the import to automatically update to the latest version. You are given a chance to confirm (or cancel) the unlocking action. - Clicking the unlock symbol will toggle the lock state to "locked", ensuring that import stays at the listed version, regardless of whether there are newer versions of it available to import. - To lock or unlock all imports at once: - In the Dependency versions pane, there is a menu (). Under that menu are the items **Lock all** and **Unlock all**. - Click **Lock all** to lock the versions of all imported items at the currently imported revision. - Click **Unlock all** to unlock all imported items and have them automatically update to the latest version.36:T41d,Let's say there is an Observable user whose username is `BigFish` who belongs to two teams, Team Saltwater and Team Freshwater, and who also has a personal account. | Team | User | Notebook | | :-- | --- | --- | --- | | Saltwater | BigFish | `observablehq.com/@saltwater/BigFishOceanNotebook` | | Saltwater | BigFish | `observablehq.com/@saltwater/BigFishSeaNotebook` | | Team | User | Notebook | | :-- | --- | --- | --- | | Freshwater | BigFish | `observablehq.com/@freshwater/BigFishStreamNotebook` | The "Freshwater" notebook is in a different workspace (the `@` in the URL is different) and imports between this notebook and the previous two notebooks would be locked. | Team | User | Notebook | | :-- | --- | --- || --- | | (No team) | BigFish | `observablehq.com/@BigFish/MyPersonalNotebook` | This last notebook is also not in the same workspace as the three Team notebooks seen earlier, even though it was created by the same user. Imports between this notebook and any of the previous notebooks also will be locked.37:[{"id":"d364d09bf0d152560b1d33858fce4a8bc176209b01f03abfcac8eaaae1316f6754f49e493f8d3ef04834820e2f5936b1139692e3e94e584060c4c5f60268aa9c","href":"https://static.observableusercontent.com/files/d364d09bf0d152560b1d33858fce4a8bc176209b01f03abfcac8eaaae1316f6754f49e493f8d3ef04834820e2f5936b1139692e3e94e584060c4c5f60268aa9c","name":"Dep_versions_pane_v2.png","type":"image/png","lastModified":1651167959751.064,"size":59374}] 32:{"id":"f9a8471c83c79648","slug":"version-locking-for-notebook-imports","title":"Version locking for notebook imports","thumbnail":"1c8f858b0dca0abc6a6f896096afbdf010e0129bfe936d96ffa9a5c1358f2563","access_level":"public","create_time":"$D2022-04-27T18:50:32.282Z","update_time":"$D2023-01-30T23:58:58.282Z","view_time":null,"first_public_time":"$D2022-04-28T19:13:45.515Z","has_unpublished_edits":null,"fork":true,"stars":29,"starred":false,"owner":{"type":"team","id":"f35c755083683fe5","login":"observablehq","name":"Observable","avatar_url":"https://avatars-next.observableusercontent.com/424c6c1f7794371c9915a160519bdfb34cf34e50069fcd6def38a1a04d4e9702","tier":"enterprise_2024"},"version":1046,"publish_version":null,"role":null,"authored":false,"authors":[],"members":[{"type":"group","id":"c4990be612f2da51","login":"8788045797a2fd14","name":"Product Education","avatar_url":null,"tier":"public","role":"editor"},{"type":"team","id":"f35c755083683fe5","login":"observablehq","name":"Observable","avatar_url":"https://avatars-next.observableusercontent.com/424c6c1f7794371c9915a160519bdfb34cf34e50069fcd6def38a1a04d4e9702","tier":"enterprise_2024","role":"viewer"}],"comments":[{"id":"9c451ef7e91114ac","reply_to_id":null,"content":"I was wondering how stable the import is in case the imported Notebook gets deleted. I found that it is not stable at all. I suggest that Observable mention that.\n\nHere are my research and my thoughts about that issue: \n\nhttps://observablehq.com/@bogo/importing-a-deleted-notebook","create_time":"$D2024-01-16T13:25:54.013Z","update_time":null,"resolved":false,"user":{"type":"individual","id":"2ef085ee9265c1c9","login":"bogo","name":"Boran","avatar_url":"https://avatars-next.observableusercontent.com/ba75107d9ca67444f20c55f1bb296bf74860ef7e71b72bcd17c6db05c7eb05e1","tier":null}}],"custom_thumbnail":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":4,"collection":{"id":"b4ea105928f5b13b","slug":"observable-tips-and-tricks","title":"Observable Tips and Tricks","owner":{"id":"f35c755083683fe5","login":"observablehq","name":"Observable"}},"type":"notebook","body":{"title":"Version locking for notebook imports","cells":[{"id":0,"value":"# Version locking for notebook imports","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":182,"value":"Your Observable notebooks go through different versions, like different versions of a document. You can see these versions by clicking on the Version history icon: ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":503,"value":"Because a notebook can import content from other notebooks, Observable has added a feature called *version locking*, which addresses the issue of notebooks changing after you have imported them.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":66,"value":"## How Version Locking Helps You\nFor reference, let's look at a sample import statement:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":152,"value":"import {map} from \"@d3/interrupted-sinu-mollweide\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":158,"value":"map","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":509,"value":"This import statement imports `map` from [@d3/interrupted-sinu-mollweide](https://observablehq.com/@d3/interrupted-sinu-mollweide), but if you go to that notebook, you'll see that it imports from Mike Bostock's [@d3/world-map](https://observablehq.com/@d3/world-map). If the `@d3/world-map` notebook were upgraded in a way that broke the map imported from `@d3/interrupted-sinu-mollweide`, then without version locking, the notebook you are reading would be broken. Version locking prevents this from happening by locking the versions of imported notebooks. ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":358,"value":"Click the lock icon above the imported cell, or the Dependency versions icon ${dependencyIcon()}, in the right-hand margin of your browser window to confirm that the imported notebooks are indeed locked!","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":383,"value":"## Stability vs. Convenience\n\nWhile it was convenient to have imported notebooks automatically update, we believe that the risk of a notebook breaking outweighs the convenience of automatic updates. The default setting for new notebooks is for locked imports, meaning that you will need to manually update any imports. For example, if there are changes to `@observablehq/notebook-you-are-importing`, you will have to manually \"update\" that import. ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":210,"value":"changeNote = note(htl.html`Note: This is a change from Observable's previous behavior, but it means your notebooks will work as intended, well into the future. \nSee \"Change from Previous Observable Behavior\" further down in this notebook.`)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":750,"value":"If you choose, you can set imports to automatically update by using the unlock icon in the **Dependency versions** pane. (See [Managing Dependencies with the Dependency versions Pane](#depPane).)","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":725,"value":"For a discussion of what happens to import-using notebooks that were created before version locking was released, see [Behavior of Notebooks Created Before Version Locking](#preVPNotebooks). The information in the sections [Indirect Imports](#indirectImports) and [Cross-owner Imports](#crossOwner) is also relevant.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":104,"value":"## Indirect Imports\nVersion locking locks not just direct notebook imports but also any notebooks imported by the direct imports. These are known as *indirect imports*.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"transitiveImports","database":"$undefined"},{"id":1030,"value":"$34","pinned":false,"hidden":false,"mode":"html","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":835,"value":"In the past, Observable users could specify versions for direct imports to address the issue of changes to imports. However, this was not possible to do for indirect imports. The consequence was that indirect imports could still change and affect or break notebooks.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":283,"value":"Version locking will keep track of both your direct imports as well as any indirect imports. By default, all imports, direct and indirect, from a workspace other than your own (see [Cross-owner Imports](#crossOwner)) have their versions locked at the time of import.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":81,"value":"## Managing Dependencies with the Dependency versions Pane\n\nTo manage the import dependencies in your notebook, click the Dependency versions icon \n \n , in the right-hand margin of your browser window. The **Dependency versions** pane appears:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"depPane","database":"$undefined"},{"id":286,"value":"html`\n

\n \n

The Dependency versions pane.

\n\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":293,"value":"What the Dependency versions pane tells you:\n- The top section provides an overview of how many updates are available.\n- If there are updates available, you will have to the option to **Upgrade all** imports or select individual imports in the list below.\n- The three dots menu displays **Lock all** and **Unlock all**, so that you can lock or unlock all dependencies at once.\n- **Direct Imports** lists notebooks that you have imported directly:\n - The number represents the version number of the import.\n - The lock symbol indicates whether or not the import is locked to the listed version.\n- **Indirect Imports** conveys the same information as Direct Imports, but for notebooks imported by the notebooks listed under Direct Imports.\n ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":982,"value":"By default, every imported notebook that is owned under a different workspace (that is, the notebook has a different `@` in the URL) will be locked.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":874,"value":"$${note(htl.html`Note: If you don't recognize some of these notebooks, remember that it includes all indirect notebook dependencies in addition to the ones you directly imported. You may be surprised by how many notebooks your notebook depends on!`)}","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":314,"value":"$35","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":920,"value":"## Cross-owner Imports\nImports from a notebook not owned by the importing notebook (that is, a notebook whose URL has a different `@`) are called cross-owner imports.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"crossOwner","database":"$undefined"},{"id":928,"value":"You might be tempted to think of this as \"notebooks I created vs. notebooks someone else created,\" but that is not sufficient to distinguish same-owner from cross-owner imports. \n- You may have created a notebook but then transferred it to a different workspace (from your personal account to your Team account, for example).\n- A user outside of a team may have created a notebook but if it is transferred into a team, it will then be considered same-owner within that team.\n\nBy default, the imported version is locked at the time of import _only_ for cross-owner imports. All same-owner imports will be unlocked. ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":957,"value":"### Examples","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":959,"value":"$36","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":902,"value":"Here are the reasons for cross-owner import locking:\n\n1. Control: The user has control over all same-owner imports and is able to reconcile any incompatibilities that arise.\n2. Convenience: It would be very inconvenient, when developing across several notebooks, to have to constantly upgrade those notebooks.\n3. Security: There is a \"trust boundary\" around notebooks with the same owner, while cross-owner imports should require a manual intervention to accept changes to the code that is run.\n\nIn the case of Team notebooks, all notebooks within that team are considered \"same owner\" notebooks.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":112,"value":"## Change from Previous Observable Behavior\nPreviously, with any of the dependencies described earlier, you were always guaranteed to get the latest version of any imported content. This was similar to bookmarking the home page of a news site; you typically want to see the latest version of such a site.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":118,"value":"While this is great for a news site, this isn't great for the stability or security of a notebook. It's very easy for someone to update a notebook in a way that seems benign but breaks notebooks that import it. It's also possible for a malicious actor to create a useful notebook, wait for it to become imported by others, and make malign changes to that notebook.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":121,"value":"Observable has therefore implemented version locking so that notebooks will be more stable and secure by default.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":124,"value":"exampleNote = note(htl.html`Note: You can still set your notebook to always import the latest version of any dependencies (see \"Locking and Unlocking Imports\"); what has changed is that this is no longer the default behavior.`)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":711,"value":"## Behavior of Notebooks Created Before Version Locking\nYour existing notebooks that have imports will remain unchanged as much as possible, until you modify the notebooks:\n- Existing imports remain unlocked until they are modified or until the cell containing the import is re-evaluated.\n- If you add a new import to an existing notebook, the new import will follow the new locking behavior.\n- You can read an existing notebook without causing imports in that notebook to lock; you must re-evaluate the cells containing imports for that to happen.\n\nWe encourage you to review all of your existing notebooks and lock any imports that should be locked.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"preVPNotebooks","database":"$undefined"},{"id":128,"value":"---","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":130,"value":"## Appendix","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":134,"value":"note = ((contents) => htl.html`\n

\n ${contents}\n

\n`)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1019,"value":"dependencyIcon = () => `\n \n `","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":517,"value":"---","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"}],"files":"$W37","stdlib":"1","titling":"auto"}} 33:"$32:body"