Notebits SDK

(This README has been generated by AI with a bunch of other random notes and so needs some reworking to really useful, but I wanted to at least capture the broad strokes of the SDK setup for future reference for myself and to make it easy for other developers to use the SDK even in its early rough form - esp. for Maptio developers - I want the setup to pass the bus test.)

This repository contains the Notebits SDK, used by both the Notebits and Maptio projects. The SDK is maintained as a library within the notebits Nx monorepo and can be included in other projects (e.g. Maptio) as a git submodule.

Developing the notebits SDK for Maptio

Pushing changes from notebits to the SDK repository

Run the following command from the root of the notebits repository, assuming you have a bare repo for notebits-sdk at ../notebits-sdk:

git subtree push --prefix=libs/sdk ../notebits-sdk.git main

Pulling code changes to the notebits SDK into another project

Go to the other project (e.g. Maptio) and run:

git submodule update --remote libs/notebits-sdk

When Maptio needs changes...

How it would work (technically): Modify SDK in Maptio: Navigate to the submodule directory within Maptio: cd /Users/romek/Spaces/Projects/Maptio/Code/maptio/libs/notebits-sdk This directory is itself a Git repository (a clone of your notebits-sdk.git). You can make changes, commit them, and even create branches here. Example: Apply to README.md Run " Push Changes from Maptio's Submodule to the Shared SDK Repo: From within Maptio/libs/notebits-sdk, you can push to the notebits-sdk.git repository: Apply to README.md Run

(This assumes origin for the submodule points to /Users/romek/Spaces/Projects/notebits/9_Code/notebits-sdk.git and you're on the main branch within the submodule). Now, your notebits-sdk.git (the local bare repo) has these new changes. Fetching Changes into notebits Monorepo (notebits/libs/sdk): This is where it gets tricky with your git subtree setup. git subtree is primarily designed for pushing out of a monorepo subdirectory. Pulling changes into that subdirectory from an external repository that has diverged is more complex. Option A (Manual Sync - Simpler, More Control): Clone the updated notebits-sdk.git to a temporary location: Apply to README.md Run sync Navigate to your notebits monorepo: cd /Users/romek/Spaces/Projects/notebits/9_Code/notebits Manually copy the changed files from /tmp/temp-sdk-sync over the files in libs/sdk. Be careful here to handle merges or conflicts if any. Commit these changes in the notebits monorepo: Apply to README.md Run " Option B (git subtree pull - More Automated, Can Be Complex): This is generally not recommended if the history in notebits-sdk.git has been contributed from multiple places without careful coordination, as subtree pull can sometimes have unexpected merge outcomes. The command would look something like this from the root of the notebits repo: git subtree pull --prefix=libs/sdk /Users/romek/Spaces/Projects/notebits/9_Code/notebits-sdk.git main --squash (Using --squash might simplify the history brought into notebits). You'd need to resolve any conflicts.

## Recommended Workflow (Maintain Source of Truth in notebits):

It's generally best to stick to the workflow where all SDK changes originate in notebits/libs/sdk:

If you're working in Maptio and identify a needed SDK change:

• Switch to your notebits monorepo.
• Make the change in notebits/libs/sdk.
• Use npm link (as described in the README) to test these live changes in Maptio.
• Once satisfied, commit the change in notebits.
• Run git subtree push --prefix=libs/sdk ../notebits-sdk.git main from the notebits root.
• In Maptio, run git submodule update --remote libs/notebits-sdk and commit the updated submodule pointer.

This maintains a clear, unidirectional flow for the SDK's authoritative code and aligns with the setup we've created.

For Developers Consuming the SDK (e.g. in the Maptio project)

If you are primarily working on e.g. Maptio and consuming the SDK (i.e., you do not have or need access to the notebits monorepo):

Initial Setup

When you first clone the Maptio repository, or if you've pulled changes that introduced this submodule, the libs/notebits-sdk directory might be empty. To initialize and fetch the SDK code, run the following command from the root of the Maptio repository:

git submodule update --init --recursive

This command will populate this libs/notebits-sdk directory with the correct version of the SDK as specified by the Maptio project.

Updating the SDK to a Newer Version

When a new version of the SDK is ready and the Maptio project has been updated to point to it, simply pulling the latest changes for the Maptio main branch should update the submodule reference. After pulling, if the submodule content doesn't automatically update, or to ensure you have the latest referenced version:

git submodule update --recursive

If project maintainers announce that the submodule itself needs to point to a newer commit not yet referenced by Maptio's main branch (less common), you might be instructed to run:

git submodule update --remote libs/notebits-sdk

Followed by committing the change to the submodule pointer in Maptio. Typically, you'll get submodule updates via a normal git pull from Maptio's main branch.

For SDK Developers (Modifying the SDK - Requires notebits Repo Access)

If you need to make changes to the Notebits SDK itself, the source of truth for the SDK resides in the notebits monorepo (typically at libs/sdk within that project).

Local Development & Rapid Iteration (SDK Changes Tested in Maptio)

For a faster feedback loop when actively developing the SDK and testing changes in Maptio simultaneously:

1. Navigate to the notebits Monorepo: Open a terminal in your local clone of the notebits monorepo (e.g., /Users/romek/Spaces/Projects/notebits/9_Code/notebits).

2. Make SDK Changes: Modify the SDK code located at libs/sdk within the notebits monorepo.

3. Build the SDK (in notebits): Run the SDK's build command from the root of the notebits monorepo.

   # In the notebits monorepo root
   nx build sdk

4. Link the Local SDK Build (in notebits): Navigate to the build output directory of the SDK in notebits (usually dist/libs/sdk):

   # In the notebits monorepo root
   cd dist/libs/sdk
   npm link
   cd ../../.. # Navigate back to notebits root

   (If your SDK is scoped, e.g., @your-org/sdk, npm link will register it under that name. Note this name for the next step.)

5. Link in Maptio: Navigate to your Maptio monorepo root (/Users/romek/Spaces/Projects/Maptio/Code/maptio):

   # In the Maptio monorepo root
   npm link <sdk-package-name>

   Replace <sdk-package-name> with the actual name of your SDK package as defined in its package.json (e.g., notebits-sdk or @notebits/sdk). You can find this name in the package.json file of the notebits/libs/sdk library.

   Now, Maptio will use your locally built SDK from notebits. Changes you make in notebits (followed by a rebuild and, if necessary, restarting Maptio's dev server) will be reflected when you run/build Maptio.

Finalizing SDK Changes (Publishing to Maptio)

Once you're satisfied with your SDK modifications and they've been tested:

1. Commit SDK Changes in notebits: In the notebits monorepo, commit your changes to the SDK.

2. Push SDK to Shared Repository (from notebits): From the root of the notebits monorepo, push the SDK changes to the shared SDK repository:

   # In the notebits monorepo root
   git subtree push --prefix=libs/sdk /Users/romek/Spaces/Projects/notebits/9_Code/notebits-sdk.git main

   (Note: If the shared SDK repository eventually moves to a remote like GitHub, this URL will need to be updated.)

3. Unlink in Maptio (Recommended): To ensure Maptio reverts to using the versioned submodule from the shared repository rather than the locally linked version:

   # In the Maptio monorepo root
   npm unlink <sdk-package-name>
   # It's good practice to run `npm install` or ensure your
   # package-lock.json/yarn.lock is consistent.
   npm install

4. Update Submodule in Maptio: In the Maptio monorepo root, pull the latest changes for the submodule:

   # In the Maptio monorepo root
   git submodule update --remote libs/notebits-sdk

   This fetches the latest from the shared SDK repo (that you just pushed to) into your Maptio/libs/notebits-sdk directory and updates the submodule's checked-out commit.

5. Commit Submodule Update in Maptio: The previous step changes which commit the libs/notebits-sdk submodule points to. Stage this change and commit it to the Maptio repository:

   # In the Maptio monorepo root
   git add libs/notebits-sdk
   git commit -m "Update notebits-sdk to latest version"
   git push # Push Maptio changes to its remote repository

This setup allows Maptio to use a version-controlled, stable version of the SDK while enabling rapid local development and testing for those working on the SDK itself. Remember to replace <sdk-package-name> with the actual package name of your SDK.