Introduction

Tymly is the product of many inter-related Node.js packages. The source code for all these packages is maintained in separate GitHub repositories in the WMFS organization.

However, for those wanting to develop the Tymly framework itself, it can be tricky to keep-track as new Tymly repos are added and existing Tymly repos evolve. It's also important to ensure all these repos are linked together locally for the best possible developer experience.

And that's what this repo can help with!

Here we have an empty Lerna-powered monorepo. By following the instructions below, it's possible to automatically fill the empty /packages, /plugins, /blueprints, /cardscript, /apps, /mods and /e2e directories with the freshest Tymly code from https://github.com/wmfs.

• Subsequent synchronization attempts will update local repos as necessary, and clone anything new that's become available.
• Repos you're working on are safe: if you've checked out a branch, sync won't touch it. It just tells you what's new on master.

Environment

There are a couple of things you'll need installed for all this to work...

Git

Git is a version-control system for tracking changes in computer files and coordinating work on those files among multiple people.

• https://git-scm.com/downloads

Node.js

Node.js is an open-source, cross-platform JavaScript run-time environment that executes JavaScript code outside of a browser.

• https://nodejs.org
• Node v20 or later is required.

Lerna

We use the Lerna tool tool to link together all the various Tymly packages, and also "hoist" shared dependencies to help reduce space/memory overheads.

With Node installed, install Lerna globally via this command:

npm install lerna@6 -g

Lerna 7 and later removed the lerna bootstrap and lerna link commands used by npm run bootstrap, so stick with version 6 for now.

GitHub Access Token

Instead of using your GitHub password, we use a Personal Github Access Token. This approach provides a few advantages - in particular finer access control and more specific monitoring. Be sure to keep the value of your Access Token value secret!

Assuming you've already signed-up with GitHub, you'll need to create a new Access Token for all your Tymly-related interactions.

• Generating a new token value is easy enough, first go here:
  • https://github.com/settings/tokens
• Then click the "Generate new token" button.
• Feel free to give your new token any name you like, but something like "Tymly Monorepo" will be fine.
• As for those Scopes, click this one:
  • repo (Full control of private repositories)
• Then hit "Generate token".
• Copy the token value: we'll be setting an environment variable to it later.

If you use a fine-grained token instead, give it read access to Contents and Metadata for the wmfs organization's repositories.

Git Credentials

The token above is only used to ask GitHub which repos exist. Cloning and fetching use your own git credentials, so git needs to be able to reach private wmfs repos without asking for a password:

• On Windows and macOS, Git Credential Manager (included with Git for Windows) handles this. Signing in once is enough.
• Alternatively, if you use the GitHub CLI, run gh auth setup-git.

Sync runs git without interactive prompts, so if your credentials are missing, the affected private repos are reported as errors rather than leaving sync waiting for a password.

Cloning

Next you'll need to clone this repo. From the Git shell:

git clone https://github.com/wmfs/tymly.git

Then, from the command prompt, install all the Node.js packages required to make this repo work:

cd tymly
npm install

Environment Variables

To integrate this repo with your GitHub account, an environment variable will need defining...

Environment Variable	Notes
TYMLY_GITHUB_TOKEN	And the value of this environment variable should be set to the personal Access Token you previously generated.

Synchronizing

Nearly there! 😃

To synchronize your empty Tymly monorepo, run this from within the /tymly directory:

npm run sync

Which will:

• Connect to GitHub (using the token in TYMLY_GITHUB_TOKEN) and find every Tymly repo in the WMFS organization.
• Clone any you don't have yet into the right directory.
• Update the ones you do have, where it's safe to:
  • On master with no local changes: fast-forwarded to the latest commit.
  • On another branch: left exactly as it is. Sync fetches, then tells you how many new commits are on master so you can merge or rebase when you're ready.
  • Uncommitted changes, unpushed commits, or a merge or rebase in progress: left alone and listed under Needs your attention.

...which should lead to output looking similar to:

Downloading repo information from https://github.com/wmfs
  Cloned      plugins/tymly-rbac-plugin
  On branch   plugins/tymly-pg-plugin  (feature/connection-pool, master has 1 new commit)
  Updated     plugins/tymly-core  (pulled 1 commit)

Cloned (1)
  plugins/tymly-rbac-plugin Plugin for Tymly

Updated (1)
  plugins/tymly-core 1 new commit
    ff3037f fix: handle missing state machine (Jane Smith, 2 hours ago)

Needs your attention (1)
  plugins/tymly-pg-plugin On feature/connection-pool: master has 1 commit(s) you don't
    8ccdfe1 feat: support schema search paths (Jane Smith, 3 hours ago)

1 up to date, 1 cloned, 1 updated, 1 need attention, 0 errors

Dependencies may have changed. Reinstall/relink before running anything.

Done (14 seconds).

Just npm run sync anytime you want to ensure your local Tymly repos reflect those on GitHub.

Options

Command	What it does
npm run sync:dry	Shows what sync would do, without changing anything.
npm run sync:verbose	Also lists every repo that was skipped, and why.
npm run sync public-only	Only syncs public packages.
npm run sync -- --concurrency=4	Works on fewer repos at once (the default is 6). Useful on slow connections.

Options can be combined, for example npm run sync -- --dry-run public-only.

If anything fails, sync finishes the other repos, lists the failures under Errors, and exits with a non-zero code.

Which repos are synced, and where

A repo is synced if its package.json has tymly in its keywords. The directory it goes into comes from its other keywords:

Keyword	Directory
e2e	/e2e
mod	/mods
app	/apps
cardscript	/cardscript
blueprint	/blueprints
plugin	/plugins
package	/packages

If a repo has more than one of these keywords, the one highest in the table wins. To choose the directory explicitly instead, add it to the repo's package.json:

"config": {
  "tymly": { "type": "blueprint" }
}

To stop a repo from being synced at all, set "sync": false in the same place:

"config": {
  "tymly": { "sync": false }
}

Bootstrapping

After synchronizing, this message may appear:

Dependencies may have changed. Reinstall/relink before running anything.

It's shown when a repo was cloned or an update changed a package.json. When you see it, from within the /tymly directory, you'll need to:

npm run bootstrap

And after a while, you're good to go! 😅

Next steps

With your Tymly repos cloned and packages installed, what next?

1. Check out our Tymly docs site.
2. Have a read of our contributor Code of Conduct.
3. Also, please read our notes about contributing.

License

MIT